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

# Agents

> Invoke a managed agent — system prompt, knowledge, routing preset — through a single endpoint.

`POST /v1/agents/runs`

Invoke any of your account's agents by passing the agent identifier in the request body,

## Request

```json theme={null}
{
  "agent": "agt_06F7557C5CM18FNXB2V5D4V72R",
  "input": "What does the privacy spec promise?",
  "conversation_id": null
}
```

| Field             | Type   | Required | Notes                                                            |
| ----------------- | ------ | -------- | ---------------------------------------------------------------- |
| `agent`           | string | yes      | Agent identifier (`agt_…`) from the portal or `POST /v1/agents`. |
| `input`           | string | yes      | End-user message. Up to 8000 chars.                              |
| `conversation_id` | string | no       | Continue an existing conversation. Omit to auto-create one.      |

To stream the response, append `?stream=true` and read the body as Server-Sent Events. See
[Streaming](#streaming) below.

## Response

```json theme={null}
{
  "id": "msg_…",
  "agent_id": "agt_…",
  "conversation_id": "conv_…",
  "output": "MESH classifies every call into one of four privacy classes…",
  "sources": [{ "documentId": "doc_…", "chunkId": "chk_…", "score": 0.82 }],
  "usage": {
    "input_tokens": 142,
    "output_tokens": 318
  },
  "route": {
    "tier": "auto",
    "model": "mesh/claude-sonnet-4"
  }
}
```

## Examples

### curl

```bash theme={null}
curl -X POST https://api.meshrouter.app/v1/agents/runs \
  -H "Authorization: Bearer $MESH_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "agent": "agt_06F7557C5CM18FNXB2V5D4V72R",
    "input": "Your question here"
  }'
```

### TypeScript (`@meshrouter/sdk` ≥ 0.2.0)

```ts theme={null}
import { Mesh } from '@meshrouter/sdk';

const mesh = new Mesh({ apiKey: process.env.MESH_API_KEY! });

const run = await mesh.agents.run({
  agent: 'agt_06F7557C5CM18FNXB2V5D4V72R',
  input: 'Your question here',
});

console.log(run.output);
```

### Python (`meshrouter` ≥ 0.2.0)

```python theme={null}
import os
from meshrouter import MeshClient

mesh = MeshClient(api_key=os.environ["MESH_API_KEY"])

run = mesh.invoke_agent(
    agent="agt_06F7557C5CM18FNXB2V5D4V72R",
    input="Your question here",
)

print(run.data["output"])
```

## Streaming

Add `?stream=true` to receive Server-Sent Events as the agent generates output. Events are
line-delimited; each carries `event:` and `data:` lines in the standard SSE format.

### TypeScript

```ts theme={null}
for await (const chunk of mesh.agents.stream({
  agent: 'agt_…',
  input: 'Your question here',
})) {
  if (chunk.delta) process.stdout.write(chunk.delta);
}
```

### Python

```python theme={null}
for event in mesh.stream_agent(
    agent="agt_…",
    input="Your question here",
):
    print(event.event, event.data)
```

## Authentication

Send the API key with `Authorization: Bearer mesh_live_…`. The key must carry the `chat` scope.
Issue keys from the portal under **API keys**.

## Errors

| Status | `code`                        | When                                                                                        |
| ------ | ----------------------------- | ------------------------------------------------------------------------------------------- |
| 400    | `invalid_request`             | Missing `agent` or `input`, or body is not valid JSON.                                      |
| 401    | `unauthorized`                | API key missing or rejected.                                                                |
| 402    | `insufficient_funds`          | Account credit balance can't cover the reserved estimate for this call.                     |
| 404    | `not_found`                   | Agent id does not belong to this account, or the supplied `conversation_id` does not exist. |
| 429    | `conversation_limit_exceeded` | Agent has reached its per-agent conversation cap.                                           |

## Legacy endpoint

`POST /v1/agents/{agentId}/chat` (agent id in URL, no `agent` body field) still works for the
moment. Responses carry a `Deprecation: true` header and a `Sunset` date — switch your clients to
`POST /v1/agents/runs` before the sunset to avoid breakage.