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

# Chat with Agent

> Send a message to an agent and get a response.

Send a message to an agent and get a response.

### Request body

`ConversationRequest`

<ParamField body="messages" type="object[]" required>
  List of conversation messages (append-only when conversation\_id is set)
</ParamField>

<ParamField body="conversation_id" type="string,null">
  Conversation identifier
</ParamField>

<ParamField body="user_id" type="string,null">
  User identifier
</ParamField>

<ParamField body="max_tokens" type="integer">
  Maximum tokens in response
</ParamField>

<ParamField body="temperature" type="number">
  Response temperature
</ParamField>

<ParamField body="stream" type="boolean">
  Whether to stream the response
</ParamField>

<ParamField body="context" type="object,null">
  Additional context
</ParamField>

### Response

`ConversationResponse`

<ResponseField name="response" type="string" required>
  Agent's response
</ResponseField>

<ResponseField name="conversation_id" type="string" required>
  Conversation identifier
</ResponseField>

<ResponseField name="tokens_used" type="integer" required>
  Number of tokens used
</ResponseField>

<ResponseField name="processing_time" type="number" required>
  Processing time in seconds
</ResponseField>

<ResponseField name="metadata" type="object">
  Additional metadata
</ResponseField>

### Status codes

| Code  | Meaning                 |
| ----- | ----------------------- |
| `200` | Successful response     |
| `400` | Invalid input           |
| `401` | Authentication required |
| `404` | Agent not found         |
| `422` | Validation Error        |
| `429` | Rate limit exceeded     |
| `500` | Internal server error   |

<RequestExample>
  ```bash cURL theme={null}
  curl --request POST \
    --url 'http://localhost:8000/conversations' \
    --header 'Authorization: Bearer YOUR_API_KEY' \
    --header 'Content-Type: application/json' \
    --data '{
    "context": {
      "goal": "Plan a 4-day trip to Kyoto",
      "plan_goal": "Plan a 4-day trip to Osaka",
      "plan_update": {
        "action": "advance"
      }
    },
    "conversation_id": "demo-trip",
    "max_tokens": 256,
    "messages": [
      {
        "content": "You are a helpful assistant.",
        "role": "system"
      },
      {
        "content": "Hello! How can you help me?",
        "role": "user"
      }
    ],
    "stream": false,
    "temperature": 0.7
  }'
  ```
</RequestExample>

<ResponseExample>
  ```json 200 theme={null}
  {
    "response": "string",
    "conversation_id": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
    "tokens_used": 1,
    "processing_time": 1.5,
    "metadata": {}
  }
  ```
</ResponseExample>