> For the complete documentation index, see [llms.txt](https://docs.guayaba.run/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.guayaba.run/documentation/api-guide/interactive-blocks.md).

# Chat

Send messages to your agents programmatically. Supports synchronous JSON responses and real-time SSE streaming.

```
POST /agents/{id}/chat
```

**Auth**: Master key or agent key with `chat` scope. **Cost**: 1 credit per message (base) + LLM cost from the runtime.

### Request

```
{
  "message": "What's the weather in Madrid?",
  "sessionKey": "api:550e8400-e29b-41d4-a716-446655440000",
  "stream": false
}
```

| Field        | Type    | Required | Description                                                                   |
| ------------ | ------- | -------- | ----------------------------------------------------------------------------- |
| `message`    | string  | Yes      | The user message (max 32,000 chars)                                           |
| `sessionKey` | string  | No       | Reuse an existing session. Must start with `api:`. Auto-generated if omitted. |
| `stream`     | boolean | No       | `true` for SSE streaming, `false` (default) for sync JSON                     |

### Sync Response

When `stream` is `false` (default), the API waits for the full agent response and returns it as JSON.

```
curl -X POST https://api.guayaba.run/api/v1/agents/550e8400-.../chat \
  -H "Authorization: Bearer g_master_YOUR_KEY" \
  -H "Content-Type: application/json" \
  -d '{"message": "Hello, what can you do?"}'
```

**Response** (`200`):

```
{
  "success": true,
  "data": {
    "sessionKey": "api:550e8400-e29b-41d4-a716-446655440000",
    "message": {
      "role": "assistant",
      "content": "I can help you with a variety of tasks..."
    }
  }
}
```

### Streaming Response (SSE)

When `stream` is `true`, the response is a `text/event-stream` with incremental events.

```
curl -X POST https://api.guayaba.run/api/v1/agents/550e8400-.../chat \
  -H "Authorization: Bearer g_master_YOUR_KEY" \
  -H "Content-Type: application/json" \
  -d '{"message": "Explain quantum computing", "stream": true}'
```

**Event stream**:

```
data: {"type":"session","sessionKey":"api:550e8400-..."}

data: {"type":"delta","text":"Quantum"}

data: {"type":"delta","text":"Quantum computing is"}

data: {"type":"tool","name":"search","phase":"start"}

data: {"type":"tool","name":"search","phase":"result","result":"..."}

data: {"type":"delta","text":"Quantum computing is a type of computation..."}

data: {"type":"done","sessionKey":"api:550e8400-..."}
```

#### Event Types

| Type      | Description                                                                                      |
| --------- | ------------------------------------------------------------------------------------------------ |
| `session` | First event. Contains the `sessionKey` for this conversation.                                    |
| `delta`   | Incremental text from the assistant. The `text` field contains the accumulated content so far.   |
| `tool`    | Tool call lifecycle. `phase: "start"` when a tool is invoked, `phase: "result"` with the output. |
| `done`    | Final event. The stream is complete.                                                             |

### Sessions

Each chat message belongs to a **session**. Sessions allow multi-turn conversations where the agent remembers previous context.

* If you omit `sessionKey`, a new session is created automatically with an `api:` prefix.
* To continue a conversation, pass the `sessionKey` returned in the first response.
* Sessions created via the API are prefixed with `api:` to distinguish them from UI sessions.

```
# First message — new session created
curl -X POST .../chat -d '{"message": "What is Rust?"}'
# Response: sessionKey = "api:abc123..."

# Follow-up — same session
curl -X POST .../chat -d '{"message": "How does its borrow checker work?", "sessionKey": "api:abc123..."}'
```

You can manage sessions (list, rename, archive, delete) through the [Sessions endpoints](https://github.com/guayabadotrun/gene-seed/blob/main/public/api/agents.md#sessions).

### Tool Calls

Agents can use tools (web search, code execution, etc.) during a conversation. In streaming mode, tool calls appear as `tool` events with `phase: "start"` and `phase: "result"`. In sync mode, the final response includes the result after all tools have completed.

Tool calls are auto-approved — no user confirmation is needed when using the API.

### Errors

| Code  | Meaning                                              |
| ----- | ---------------------------------------------------- |
| `401` | Invalid or missing API key                           |
| `402` | Insufficient credits                                 |
| `403` | Key lacks `chat` scope or cannot access this agent   |
| `404` | Agent not found                                      |
| `409` | Agent is not running                                 |
| `422` | Validation error (missing `message`, too long, etc.) |
| `502` | Agent container unreachable                          |
