#Chat API

与 Agent 进行对话，支持流式和非流式两种模式，以及自动对话历史管理。

基础路径: /v1/agents/:agentId/chat

#发送消息

POST /v1/agents/:agentId/chat

所需权限: agent:chat

Chat API 支持两种请求格式：

#新格式（推荐）

后端自动管理对话历史，支持会话持久化。

json{
  "message": "你好，请帮我分析这个问题",
  "sessionId": "sess_abc123",
  "stream": true,
  "options": {
    "model": "zhipu/glm-4"
  },
  "hint": {
    "planning": "auto",
    "onStepFailure": "continue"
  }
}

字段	类型	必填	说明
`message`	string \	ContentBlock[]	是	用户消息内容（字符串为纯文本，数组为多模态）
`sessionId`	string	否	会话 ID。省略则自动创建新会话
`stream`	boolean	否	是否启用流式响应，默认 false
`options.model`	string	否	覆盖 Agent 默认模型
`hint.planning`	string	否	规划模式：`force`、`auto`、`none`
`hint.onStepFailure`	string	否	步骤失败策略：`stop`、`continue`、`auto`

#图片消息（多模态）

发送图片时，message 字段使用 OpenAI 标准的 ContentBlock[] 格式：

json{
  "message": [
    { "type": "text", "text": "这张图片里是什么？" },
    { "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
}

字段	类型	说明
`type`	`"text"`	文本内容块
`text`	string	文本内容
`type`	`"image_url"`	图片内容块
`image_url.url`	string	图片 URL（支持 `https://` 链接和 `data:image/...;base64,...` 格式）

约束：

每条消息最多 9 张图片
必须包含至少 一个文本块
Agent 的模型必须支持视觉理解（如 qwen3-max、qwen3.5-plus）。不支持视觉的模型会返回 400 错误："The current model does not support image understanding."
图片 URL 存储在 metadata.imageUrls 中，会在对话历史中展示

#旧格式（向后兼容）

前端管理消息列表，无历史持久化。

json{
  "messages": [
    { "role": "system", "content": "你是一个 AI 助手" },
    { "role": "user", "content": "你好" }
  ],
  "stream": true
}

字段	类型	必填	说明
`messages`	array	是	消息列表
`stream`	boolean	否	是否启用流式响应

系统通过检测请求体中是否存在 message 字段（string 类型）且不存在 messages 字段来自动区分新旧格式。

#非流式响应

当 stream: false 或未指定时：

json{
  "sessionId": "sess_abc123",
  "id": "chatcmpl-xxx",
  "agentId": "agent_abc123",
  "message": {
    "role": "assistant",
    "content": "你好！我是你的 AI 助手。有什么我可以帮你的吗？"
  },
  "usage": {
    "inputTokens": 50,
    "outputTokens": 30,
    "totalTokens": 80
  },
  "sources": [
    {
      "documentId": "doc_xxx",
      "title": "产品手册",
      "chunk": "相关文档片段...",
      "score": 0.92
    }
  ],
  "toolsCalled": [
    {
      "name": "web-search",
      "arguments": { "query": "最新消息" }
    }
  ],
  "skillsUsed": ["customer-service"],
  "latency": 1250,
  "createdAt": "2026-02-20T10:00:00Z"
}

#流式响应

当 stream: true 时，响应使用 SSE (Server-Sent Events) 格式：

Content-Type: text/event-stream

#SSE 事件格式

每个事件以 data: 前缀开头，以 \n\n 结尾：

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

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

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

data: [DONE]

#事件字段说明

字段	说明
`sessionId`	会话 ID
`delta.content`	增量文本内容
`toolCall`	工具调用事件（见 Agentic Streaming）
`toolResult`	工具执行结果（见 Agentic Streaming）
`thinking`	思维链事件（见 Agentic Streaming）
`plan`	规划事件（见 Agentic Streaming）
`done`	流结束标记
`usage`	Token 用量统计
`sources`	RAG 引用来源
`error`	错误信息

#对话会话管理

使用新格式时，系统自动管理对话会话。你也可以通过以下端点直接管理会话。

#列出会话

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

所需权限: session:read

#查询参数

参数	类型	说明
`page`	number	页码，默认 1
`limit`	number	每页条数，默认 20
`status`	string	按状态筛选

#响应

json{
  "data": [
    {
      "id": "sess_abc123",
      "agentId": "agent_xxx",
      "title": "关于产品功能的讨论",
      "status": "active",
      "messageCount": 12,
      "totalTokens": 3500,
      "summary": "用户询问了产品的主要功能...",
      "createdAt": "2026-02-20T08:00:00Z",
      "updatedAt": "2026-02-20T10:00:00Z"
    }
  ],
  "meta": {
    "total": 5,
    "page": 1,
    "limit": 20,
    "totalPages": 1
  }
}

#获取会话详情

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

所需权限: session:read

#更新会话

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

所需权限: session:update

#请求体

json{
  "title": "新的会话标题",
  "status": "archived"
}

#删除会话

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

所需权限: session:delete

#响应

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

#获取会话消息

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

所需权限: messages:read

#查询参数

参数	类型	说明
`page`	number	页码，默认 1
`limit`	number	每页条数，默认 50，最大 100

#响应

json{
  "data": [
    {
      "id": "msg_xxx",
      "sessionId": "sess_abc123",
      "role": "user",
      "content": "你好",
      "createdAt": "2026-02-20T08:00:00Z"
    },
    {
      "id": "msg_yyy",
      "sessionId": "sess_abc123",
      "role": "assistant",
      "content": "你好！有什么我可以帮助你的吗？",
      "metadata": {
        "thinking": "用户发来了问候...",
        "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（旧版）

以下端点使用旧版 Storage 模块，主要用于向后兼容。建议新集成使用上述 Chat Sessions API。

#创建会话

POST /v1/agents/:agentId/sessions

所需权限: session:create

#请求体

json{
  "title": "新会话",
  "metadata": {}
}

#获取消息历史

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

所需权限: messages:read

#查询参数

参数	类型	说明
`limit`	number	返回条数
`offset`	number	偏移量

#响应

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