> ## Documentation Index
> Fetch the complete documentation index at: https://docs.hyperterse.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Runtime API

> Use Hyperterse A2A v1 endpoints mounted per agent.

For how A2A fits next to MCP at runtime, see [A2A transport](/runtime/a2a-transport).

Each agent is exposed behind its own route prefix:

```text theme={null}
/agent/{agentName}
```

So a `support` agent gets:

* `GET /agent/support/.well-known/agent-card.json`
* `POST /agent/support`

## What the endpoint serves

The A2A mount provides a stateful agent contract over one JSON-RPC endpoint:

* agent discovery via the public card
* request/response execution
* SSE streaming
* task retrieval, cancellation, and resubscription
* push-notification config operations

## Endpoint reference

| Endpoint                                         | Method(s) | Purpose                           |
| ------------------------------------------------ | --------- | --------------------------------- |
| `/agent/{agentName}/.well-known/agent-card.json` | `GET`     | Return the public A2A agent card. |
| `/agent/{agentName}`                             | `POST`    | Serve A2A v1 JSON-RPC methods.    |

## Supported JSON-RPC methods

* `SendMessage`
* `SendStreamingMessage`
* `GetTask`
* `ListTasks`
* `CancelTask`
* `SubscribeToTask`
* `GetTaskPushNotificationConfig`
* `ListTaskPushNotificationConfigs`
* `CreateTaskPushNotificationConfig`
* `DeleteTaskPushNotificationConfig`
* `GetExtendedAgentCard`

## Request body contract

`SendMessage` and `SendStreamingMessage` use this shape:

```json theme={null}
{
  "jsonrpc": "2.0",
  "id": 1,
  "method": "SendMessage",
  "params": {
    "message": {
      "role": "user",
      "parts": [{ "text": "Find pending orders" }]
    }
  }
}
```

Streaming uses the same payload but changes `method` to
`SendStreamingMessage`.

## Typical flow (recommended)

1. `GET /agent/{agentName}/.well-known/agent-card.json`
2. `POST /agent/{agentName}` with `SendMessage` or `SendStreamingMessage`
3. If you receive a task result, use `GetTask` for later polling
4. Use `SubscribeToTask` for SSE replay of task events

<Tip>
  Continuity is task-based: use task IDs to poll, stream, or resume work across
  turns.
</Tip>

## Request examples

### SendMessage

```bash theme={null}
curl -s -X POST http://localhost:8080/agent/support \
  -H "Content-Type: application/json" \
  -d '{
    "jsonrpc": "2.0",
    "id": 1,
    "method": "SendMessage",
    "params": {
      "message": {
        "role": "user",
        "parts": [{ "text": "Find all pending orders from today" }]
      }
    }
  }' | jq
```

### SendStreamingMessage

```bash theme={null}
curl -N -X POST http://localhost:8080/agent/support \
  -H "Content-Type: application/json" \
  -H "Accept: text/event-stream" \
  -d '{
    "jsonrpc": "2.0",
    "id": 2,
    "method": "SendStreamingMessage",
    "params": {
      "message": {
        "role": "user",
        "parts": [{ "text": "Summarize pending orders in 3 bullets" }]
      }
    }
  }'
```

### GetTask

```bash theme={null}
curl -s -X POST http://localhost:8080/agent/support \
  -H "Content-Type: application/json" \
  -d '{
    "jsonrpc": "2.0",
    "id": 3,
    "method": "GetTask",
    "params": { "id": "<task-id>" }
  }' | jq
```

### SubscribeToTask

```bash theme={null}
curl -N -X POST http://localhost:8080/agent/support \
  -H "Content-Type: application/json" \
  -H "Accept: text/event-stream" \
  -d '{
    "jsonrpc": "2.0",
    "id": 4,
    "method": "SubscribeToTask",
    "params": { "id": "<task-id>" }
  }'
```

## Operational notes

* `SendMessage` can return a task-shaped result when execution is stateful.
* Tool permissions follow the allowlist in each agent's config.
* On model reload, agent routes match your latest declarations.
* CORS headers are set on agent routes for browser-friendly access.

## Troubleshooting

<Warning>
  If tool invocation is unexpectedly blocked, check the agent's `tool_access`
  policy and root defaults in `.hyperterse`.
</Warning>

Next: configure providers in [Model providers](/agents/model-providers) and tune permission policy in [Tool access](/agents/tool-access).