> For the complete documentation index, see [llms.txt](https://dnotifier.gitbook.io/product-docs/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://dnotifier.gitbook.io/product-docs/workflows-and-agents/a2a.md).

# Agent-to-agent (A2A)

Agents and workflows built with the SDK can also talk over the open [Agent2Agent (A2A) protocol](https://a2a-protocol.org). Any A2A-compatible agent or framework can discover your agents through an **Agent Card** and send them messages over JSON-RPC.

```
  A2A client (another agent, framework, or your code)
         │  HTTPS + X-API-Key
         ▼
  DNotifier A2A endpoint
         │  realtime
         ▼
  Your process: agent.listen(notifier)
         │
         ▼
  Agent runs and replies to the caller
```

## 1. Turn on the capability

Set `a2a: true` in the agent's or workflow's `capabilities`. You can enable it together with `mcpServer`.

{% tabs %}
{% tab title="JavaScript" %}

```js
const agent = DNotifier.defineAgent({
  name: "mermaid-diagram",
  description: "Generates Mermaid diagrams from a plain-language request.",
  instructions: "Write a Mermaid diagram for the user's request and validate it.",
  tools,
  capabilities: { a2a: true, mcpServer: true },
});
```

{% endtab %}

{% tab title="Python" %}

```python
agent = define_agent(
    name="mermaid-diagram",
    description="Generates Mermaid diagrams from a plain-language request.",
    instructions="Write a Mermaid diagram for the user's request and validate it.",
    tools=tools,
    capabilities={"a2a": True, "mcpServer": True},
)
```

{% endtab %}

{% tab title="Dart" %}

```dart
final agent = defineAgent(
  name: 'mermaid-diagram',
  description: 'Generates Mermaid diagrams from a plain-language request.',
  instructions: "Write a Mermaid diagram for the user's request and validate it.",
  tools: tools,
  capabilities: {'a2a': true, 'mcpServer': true},
);
```

{% endtab %}
{% endtabs %}

Workflows take the same `capabilities` option.

## 2. Listen

Connect over WebSocket and call `listen`, exactly as for MCP. Keep the process running; call `stopListening` to take the agent offline.

{% tabs %}
{% tab title="JavaScript" %}

```js
await notifier.connect();     // transport: "ws"
agent.listen(notifier);       // or workflow.listen(notifier)
// agent.stopListening();
```

{% endtab %}

{% tab title="Python" %}

```python
await notifier.connect()      # transport="ws"
agent.listen(notifier)        # or workflow.listen(notifier)
# agent.stop_listening()
```

{% endtab %}

{% tab title="Dart" %}

```dart
await notifier.connect();     // transport: 'ws'
agent.listen(notifier);       // or workflow.listen(notifier)
// agent.stopListening();
```

{% endtab %}
{% endtabs %}

See [**Serve agents over MCP**](https://dnotifier.gitbook.io/product-docs/workflows-and-agents/mcp-server.md#2-listen) for a full host example.

A2A invokes can include the same session / resume fields as `runAgent` (`sessionId`, `state`, `resume` / `mode`, `fromCheckpointId`). The listening host resumes from that checkpoint when they are present.

→ [Checkpoints, sessions & resume](https://dnotifier.gitbook.io/product-docs/workflows-and-agents/checkpoints.md)

## 3. Call your agents over A2A

### Endpoint and key

| Deployment                            | A2A URL                                                             |
| ------------------------------------- | ------------------------------------------------------------------- |
| Shared DNotifier plan                 | `https://api.dnotifier.com/rpc/v1/a2a`                              |
| Enterprise on-premises / custom cloud | Provided with your deployment (may be an internal, protected route) |

Authenticate with the same header used for MCP:

```
X-API-Key: <appId>:<userId>:<appSecret>
```

`userId` can be any id that names the caller (for example `planner-agent` or `partner-acme`); calls are grouped under it in observability. The key contains your app secret, so keep it out of source control.

### Agent Card

Fetch the Agent Card with `GET` on the A2A URL. It is also served at `/.well-known/agent-card.json` and `/agent-card`.

| Request             | Returns                                                        |
| ------------------- | -------------------------------------------------------------- |
| Without `X-API-Key` | Public card, without skills                                    |
| With `X-API-Key`    | Card with one skill per agent or workflow that has `a2a: true` |

```bash
curl https://api.dnotifier.com/rpc/v1/a2a \
  -H "X-API-Key: $DNOTIFIER_A2A_KEY"
```

### Send a message

`POST` a JSON-RPC request to the A2A URL with method `message/send` (`SendMessage` is also accepted). Pick the target in `message.metadata` with one of:

| Field                   | Value                                             |
| ----------------------- | ------------------------------------------------- |
| `agentName`             | The agent's `name`, for example `mermaid-diagram` |
| `agentId`               | The agent id                                      |
| `skillId` / `skillName` | A skill from the Agent Card                       |

```json
{
  "jsonrpc": "2.0",
  "id": 1,
  "method": "message/send",
  "params": {
    "message": {
      "role": "user",
      "parts": [{ "type": "text", "text": "hello" }],
      "metadata": { "agentName": "mermaid-diagram" }
    }
  }
}
```

{% tabs %}
{% tab title="curl" %}

```bash
curl https://api.dnotifier.com/rpc/v1/a2a \
  -H "Content-Type: application/json" \
  -H "X-API-Key: $DNOTIFIER_A2A_KEY" \
  -d '{
    "jsonrpc": "2.0",
    "id": 1,
    "method": "message/send",
    "params": {
      "message": {
        "role": "user",
        "parts": [{ "type": "text", "text": "Diagram a 3-tier web app" }],
        "metadata": { "agentName": "mermaid-diagram" }
      }
    }
  }'
```

{% endtab %}

{% tab title="JavaScript" %}

```js
const res = await fetch("https://api.dnotifier.com/rpc/v1/a2a", {
  method: "POST",
  headers: {
    "Content-Type": "application/json",
    "X-API-Key": process.env.DNOTIFIER_A2A_KEY,
  },
  body: JSON.stringify({
    jsonrpc: "2.0",
    id: 1,
    method: "message/send",
    params: {
      message: {
        role: "user",
        parts: [{ type: "text", text: "Diagram a 3-tier web app" }],
        metadata: { agentName: "mermaid-diagram" },
      },
    },
  }),
});
console.log(await res.json());
```

{% endtab %}

{% tab title="Python" %}

```python
import os
import httpx

res = httpx.post(
    "https://api.dnotifier.com/rpc/v1/a2a",
    headers={"X-API-Key": os.environ["DNOTIFIER_A2A_KEY"]},
    json={
        "jsonrpc": "2.0",
        "id": 1,
        "method": "message/send",
        "params": {
            "message": {
                "role": "user",
                "parts": [{"type": "text", "text": "Diagram a 3-tier web app"}],
                "metadata": {"agentName": "mermaid-diagram"},
            }
        },
    },
    timeout=120,
)
print(res.json())
```

{% endtab %}
{% endtabs %}

Agents that call tools or a model can take a while to answer, so use a generous client timeout.

### A2A SDKs and frameworks

Because the endpoint speaks standard A2A, you can also point existing A2A tooling at it — for example the [A2A Python SDK](https://github.com/a2aproject/a2a-python), the [A2A JavaScript SDK](https://github.com/a2aproject/a2a-js), or frameworks with A2A support such as [Google ADK](https://google.github.io/adk-docs/a2a/). Give them the A2A URL as the agent card location and add the `X-API-Key` header to their HTTP client.

## Limits

| Limit        | Value                                          |
| ------------ | ---------------------------------------------- |
| Request body | 1 MB JSON                                      |
| Availability | Only while the host is connected and listening |

## Troubleshooting

| Symptom                  | Check                                                                                             |
| ------------------------ | ------------------------------------------------------------------------------------------------- |
| Agent Card has no skills | Send the `X-API-Key` header, and set `capabilities: { a2a: true }` on the agent or workflow       |
| Target agent not found   | `metadata.agentName` matches the agent's `name` exactly, or use a `skillId` from the Agent Card   |
| `401` / `403`            | The key format is `<appId>:<userId>:<appSecret>` and the app id and secret belong to the same app |
| Call times out           | The host process is running, connected with `transport: "ws"`, and listening                      |

## Next steps

* [**Serve agents over MCP**](https://dnotifier.gitbook.io/product-docs/workflows-and-agents/mcp-server.md)
* [**Remote agents**](https://dnotifier.gitbook.io/product-docs/workflows-and-agents/remote-agents.md) — call agents on other servers from inside a workflow
* [**Define an agent**](https://dnotifier.gitbook.io/product-docs/workflows-and-agents/define-agent.md)
