PreviewDocs / Augments

Link

Exchange authenticated text messages with configured A2A peers over a separate HTTP listener.

Preview capability

This capability is usable, but its API and operational boundaries may change before 1.0. Pin exact versions and validate it deliberately before production use.

Outcome

What it enables

Give an agent authenticated, text-only A2A sends and inbound turns from named peer agents.

Status: Preview
Availability: Install with `auggy augment add link`; it adds `@auggy/link@^0.1.2` and defaults to port `8081`.

Contributes

toolstransport

Link is separate from webTransport: it speaks A2A JSON-RPC over its own HTTP listener while webTransport continues to serve the agent's browser-facing surfaces.

Install and configure

1Run `auggy augment add link` in the agent project and confirm the Preview prompt.
2Set the agent-card environment variables and review `augments/link/augment.yaml`.
3Run `auggy doctor`, then `bun install` if the package install was skipped; restart after changing peers or port.

augments/link/augment.yamlyaml

type: link
config:
  port: 8081
  dbPath: ./data/link.db
  agentCard:
    id: "${AUGGY_AGENT_ID}"
    name: "${AUGGY_AGENT_NAME}"
    description: Auggy link endpoint
    endpointUrl: "${AUGGY_LINK_PUBLIC_URL}"
  peers: {}

.env.env

AUGGY_AGENT_ID=00000000-0000-0000-0000-000000000001
AUGGY_AGENT_NAME=front-door
AUGGY_LINK_PUBLIC_URL=https://front-door.example.org

The install also copies `skills/link/SKILL.md` and adds `@auggy/link` to the agent package. Bearers belong in environment-backed config, not in a shared registry.

Use it

Configure one research peer with separate outbound and inbound bearers, then let the agent discover it before delegating a question.

Inline peer configurationyaml

type: link
config:
  port: 8081
  dbPath: ./data/link.db
  agentCard:
    id: "${AUGGY_AGENT_ID}"
    name: "${AUGGY_AGENT_NAME}"
    description: Front-door agent
    endpointUrl: "${AUGGY_LINK_PUBLIC_URL}"
  peers:
    researcher:
      url: https://researcher.example.org
      bearer: "${RESEARCHER_BEARER}"
      participantId: 00000000-0000-0000-0000-000000000002
      inboundBearer: "${RESEARCHER_INBOUND_BEARER}"
      inboundBearerId: researcher-front-door
      purpose: Research specialist
      examples:
        - What is the current state of test-time compute?

Model tool inputsjson

{
  "link_list": {},
  "link_send": {
    "to": "researcher",
    "text": "Summarize the latest evidence on test-time compute."
  }
}

Runtime surfaces

Surface	Exact behavior
HTTP listener	Own Bun.serve port `8081` by default; separate from webTransport.
GET /health	Link service health endpoint.
GET /.well-known/agent.json	Serves the configured agent card.
POST /a2a/v1	Bearer-authenticated A2A JSON-RPC inbound messages translated into Auggy turns.
GET /a2a/v1/stream	Present but returns the current `501` stream stub.
`link_list`	Returns configured peer names plus optional purpose and examples.
`link_send`	Sends text to a named peer; returns synchronous reply text or `{ ok: true, outcome: "task", taskId }`.
Context and storage	Adds peer names to the turn preamble; `link.db` backs the link task store.

Boundaries

Area	Current boundary
Trust	A configured inbound bearer grants that peer admission as `agent` trust. Bearer possession is an authority boundary; public or anonymous traffic is rejected before the turn.
Persistence	`link.db` is used by the link task store. Peer-source cache is in memory; inline peers remain in config. Rotate bearers separately from peer names or URLs.
Deployment	Expose and route the separate link port. Peer and registry URLs require HTTPS by default; `LINK_ALLOW_PLAINTEXT=1` is the localhost-development override.
Limitations	Traffic is text-only. Synchronous replies are supported; no model tool follows asynchronous task IDs, so a returned `taskId` has no built-in polling or completion workflow. The stream endpoint is a `501` stub.

Treat bearers as trust grants

Link bearers grant agent trust today. Do not use this listener for public or reduced-privilege peers, and do not put bearer values in a registry response.

Verify

1Run `auggy doctor` and confirm the agent card, `dbPath`, peer fields, and port parse.
2Start the agent and run `curl http://127.0.0.1:8081/health`; confirm the link listener responds independently of webTransport.
3Run `curl http://127.0.0.1:8081/.well-known/agent.json`; confirm the response matches the configured agent card.
4As Creator, call `link_list`, then `link_send` to the configured peer; confirm the peer name resolves and a synchronous text response is returned.
5Send one inbound request with the configured bearer and confirm the resulting peer identity is `agent` trust; retry without the bearer and confirm HTTP 401.

Add an augmentInstall layeredMemory, inspect what the CLI adds, and verify peer-scoped memory in Console.TransportsExpose the agent over web chat, AG-UI, Telegram, and other inbound surfaces.SecurityAuggy's security boundaries, the prompt-injection threat model, and how to report a vulnerability privately.Deploy and verifyDeploy the agent to Railway and verify its health, route, console, and application client.BudgetsGate turns and record per-peer runtime usage with SQLite-backed caps.