# Send a message to an agent and wait for its reply

`POST /v1/agents/{agent}/messages`

**In this build:** Works on the simulator or a real VM.

**Scope:** `agent.message`

**CLI:** `harebox agent send`

## Request: `SendAgentMessageRequest`

| Field | Type | Notes |
|---|---|---|
| `text` (required) | `string` |  |
| `conversation` | `string` | Continue this conversation. Omit for the agent's current one. |
| `wait_seconds` | `integer` | How long to wait for the reply. 0 answers at once; stream the sandbox's events for the reply. |

## Response: 200

`AgentMessage`

| Field | Type | Notes |
|---|---|---|
| `id` (required) | `string` |  |
| `agent` (required) | `string` |  |
| `end_user` | `string or null` |  |
| `source` | `string` | api, trigger, schedule or channel:<kind>. |
| `text` (required) | `string` |  |
| `prompt` (required) | `string` | The prompt it became, on the agent's sandbox. |
| `conversation` | `string or null` |  |
| `status` (required) | `string` | One of: `queued`, `running`, `finished`, `failed`, `interrupted`, `budget_exceeded` |
| `reply` | `string or null` | The agent's answer once its turn ends. |
| `usage` | `object or null` |  |
| `at` (required) | `string` |  |

Errors follow [one format](../errors.html).