# Link

Canonical: https://auggy.dev/docs/augment-link
Status: Preview
Package: auggy 0.5.0

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

## 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:** `tools`, `transport`

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

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

**augments/link/augment.yaml**

```yaml
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 configuration**

```yaml
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 inputs**

```json
{
  "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. |

> **Warning: 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

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

## Related

- [Add an augment](https://auggy.dev/docs/add-augment/markdown)
- [Transports](https://auggy.dev/docs/transports/markdown)
- [Security](https://auggy.dev/docs/security/markdown)
- [Deploy and verify](https://auggy.dev/docs/deploy/markdown)
- [Budgets](https://auggy.dev/docs/augment-budgets/markdown)