# 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                          |


---

# Agent Instructions: Querying This Documentation

If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter:

```
GET https://docs.guayaba.run/documentation/api-guide/interactive-blocks.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.