#Chat API

Chat with Agents, supporting both streaming and non-streaming modes, with automatic conversation history management.

Base Path: /v1/agents/:agentId/chat

#Send Message

CopyPOST /v1/agents/:agentId/chat

Required Permission: agent:chat

The Chat API supports two request formats:

#New Format (Recommended)

The backend automatically manages conversation history with session persistence support.

jsonCopy{
  "message": "Hello, please help me analyze this problem",
  "sessionId": "sess_abc123",
  "stream": true,
  "options": {
    "model": "zhipu/glm-4"
  },
  "hint": {
    "planning": "auto",
    "onStepFailure": "continue"
  }
}

#Image Messages (Multimodal)

To send images along with text, use the OpenAI-standard ContentBlock[] format for the message field:

jsonCopy{
  "message": [
    { "type": "text", "text": "What is in this image?" },
    { "type": "image_url", "image_url": { "url": "https://example.com/photo.jpg" } },
    { "type": "image_url", "image_url": { "url": "https://example.com/photo2.jpg" } }
  ],
  "sessionId": "sess_abc123",
  "stream": true
}

Constraints:

• Maximum 9 images per message
• At least one text block is required
• The Agent's model must support vision (e.g. qwen3-max, qwen3.5-plus). If the model does not support vision, a 400 error is returned: "The current model does not support image understanding."
• Images are stored in metadata.imageUrls and displayed in chat history

#Legacy Format (Backward Compatible)

The frontend manages the message list with no history persistence.

jsonCopy{
  "messages": [
    { "role": "system", "content": "You are an AI assistant" },
    { "role": "user", "content": "Hello" }
  ],
  "stream": true
}

The system automatically distinguishes between the new and legacy formats by checking whether the request body contains a message field (string type) and does not contain a messages field.

#Non-Streaming Response

When stream: false or not specified:

jsonCopy{
  "sessionId": "sess_abc123",
  "id": "chatcmpl-xxx",
  "agentId": "agent_abc123",
  "message": {
    "role": "assistant",
    "content": "Hello! I'm your AI assistant. How can I help you?"
  },
  "usage": {
    "inputTokens": 50,
    "outputTokens": 30,
    "totalTokens": 80
  },
  "sources": [
    {
      "documentId": "doc_xxx",
      "title": "Product Manual",
      "chunk": "Relevant document excerpt...",
      "score": 0.92
    }
  ],
  "toolsCalled": [
    {
      "name": "web-search",
      "arguments": { "query": "latest news" }
    }
  ],
  "skillsUsed": ["customer-service"],
  "latency": 1250,
  "createdAt": "2026-02-20T10:00:00Z"
}

#Streaming Response

When stream: true, the response uses SSE (Server-Sent Events) format:

CopyContent-Type: text/event-stream

#SSE Event Format

Each event starts with the data: prefix and ends with \n\n:

Copydata: {"sessionId":"sess_xxx","delta":{"content":"Hello"}}

data: {"sessionId":"sess_xxx","delta":{"content":"!"}}

data: {"sessionId":"sess_xxx","done":true,"usage":{...},"sources":[...]}

data: [DONE]

#Event Field Description

#Chat Session Management

When using the new format, the system automatically manages chat sessions. You can also manage sessions directly through the following endpoints.

#List Sessions

CopyGET /v1/agents/:agentId/chat-sessions

Required Permission: session:read

#Query Parameters

#Response

jsonCopy{
  "data": [
    {
      "id": "sess_abc123",
      "agentId": "agent_xxx",
      "title": "Discussion about product features",
      "status": "active",
      "messageCount": 12,
      "totalTokens": 3500,
      "summary": "The user asked about the main product features...",
      "createdAt": "2026-02-20T08:00:00Z",
      "updatedAt": "2026-02-20T10:00:00Z"
    }
  ],
  "meta": {
    "total": 5,
    "page": 1,
    "limit": 20,
    "totalPages": 1
  }
}

#Get Session Details

CopyGET /v1/agents/:agentId/chat-sessions/:sessionId

Required Permission: session:read

#Update Session

CopyPATCH /v1/agents/:agentId/chat-sessions/:sessionId

Required Permission: session:update

#Request Body

jsonCopy{
  "title": "New session title",
  "status": "archived"
}

#Delete Session

CopyDELETE /v1/agents/:agentId/chat-sessions/:sessionId

Required Permission: session:delete

#Response

jsonCopy{
  "id": "sess_abc123",
  "deleted": true
}

#Get Session Messages

CopyGET /v1/agents/:agentId/chat-sessions/:sessionId/messages

Required Permission: messages:read

#Query Parameters

#Response

jsonCopy{
  "data": [
    {
      "id": "msg_xxx",
      "sessionId": "sess_abc123",
      "role": "user",
      "content": "Hello",
      "createdAt": "2026-02-20T08:00:00Z"
    },
    {
      "id": "msg_yyy",
      "sessionId": "sess_abc123",
      "role": "assistant",
      "content": "Hello! How can I help you?",
      "metadata": {
        "thinking": "The user sent a greeting...",
        "plan": { "steps": [...] },
        "toolCalls": [...]
      },
      "inputTokens": 50,
      "outputTokens": 30,
      "totalTokens": 80,
      "createdAt": "2026-02-20T08:00:05Z"
    }
  ],
  "meta": {
    "total": 2,
    "page": 1,
    "limit": 50,
    "totalPages": 1
  }
}

#Legacy Sessions

The following endpoints use the legacy Storage module and are primarily for backward compatibility. New integrations should use the Chat Sessions API above.

#Create Session

CopyPOST /v1/agents/:agentId/sessions

Required Permission: session:create

#Request Body

jsonCopy{
  "title": "New Session",
  "metadata": {}
}

#Get Message History

CopyGET /v1/agents/:agentId/sessions/:sessionId/messages

Required Permission: messages:read

#Query Parameters

#Response

jsonCopy{
  "sessionId": "sess_xxx",
  "messages": [...],
  "totalMessages": 24
}