> ## Documentation Index > Fetch the complete documentation index at: https://docs.xpertai.cn/llms.txt > Use this file to discover all available pages before exploring further. # 调用智能体 > 向已发布的智能体发送消息，通过 SSE 接收流式回复。使用 Authorization: Bearer 或 x-api-key 鉴权。保存 on_conversation_start.data.id，并在后续请求中通过 conversationId 延续对话。每个 SSE data 字段包含 JSON，字段为 type、可选的 event 和 data。文本增量的 type 为 message，生命周期事件的 type 为 event。请检查 on_conversation_end.data.status、error 以及 SSE 错误事件：HTTP 请求成功不代表智能体执行成功。内部运行时选项不属于公开请求参数。 ## OpenAPI ````yaml /api/openapi.ai.zh-Hans.json post /api/ai/v1/chat openapi: 3.0.0 info: title: Xpert AI description: '' version: '1.0' contact: {} servers: [] security: [] tags: [] paths: /api/ai/v1/chat: post: tags: - AI/v1 summary: 调用智能体 description: >- 向已发布的智能体发送消息，通过 SSE 接收流式回复。使用 Authorization: Bearer 或 x-api-key 鉴权。保存 on_conversation_start.data.id，并在后续请求中通过 conversationId 延续对话。每个 SSE data 字段包含 JSON，字段为 type、可选的 event 和 data。文本增量的 type 为 message，生命周期事件的 type 为 event。请检查 on_conversation_end.data.status、error 以及 SSE 错误事件：HTTP 请求成功不代表智能体执行成功。内部运行时选项不属于公开请求参数。 operationId: AIV1Controller_chat requestBody: required: true content: application/json: schema: $ref: '#/components/schemas/AgentChatBody' examples: 首次发送消息: summary: 首次发送消息 value: request: action: send message: input: input: 你好，请简单介绍一下自己。 options: xpertId: YOUR_PUBLISHED_XPERT_ID 继续已有对话: summary: 继续已有对话 value: request: action: send conversationId: CONVERSATION_ID_FROM_SSE message: input: input: 请继续刚才的话题。 options: xpertId: YOUR_PUBLISHED_XPERT_ID responses: '200': description: >- SSE 事件流。若连接关闭前未收到 on_conversation_end，则本次回复不完整。解析 JSON 前忽略心跳注释，以及去除首尾空白后内容为 : keep-alive 的 data 帧。按需处理其他生命周期事件。 content: text/event-stream: schema: type: string example: >+ data: {"type":"event","event":"on_conversation_start","data":{"id":"conversation-id"}} data: {"type":"message","data":"你好"} data: {"type":"event","event":"on_conversation_end","data":{"id":"conversation-id","status":"idle","error":null}} '201': description: 部分服务端版本使用 201 返回相同的 SSE 事件流。成功的 2xx 响应应按 SSE 解析，不能作为普通 JSON 读取。 content: text/event-stream: schema: type: string example: >+ data: {"type":"event","event":"on_conversation_start","data":{"id":"conversation-id"}} data: {"type":"message","data":"你好"} data: {"type":"event","event":"on_conversation_end","data":{"id":"conversation-id","status":"idle","error":null}} '400': description: 请求无效、会话与智能体或项目不匹配，或当前执行状态不允许此操作。 '401': description: 缺少鉴权凭据，或凭据无效、已过期。 '403': description: 调用身份无权访问此智能体、会话或项目。 '404': description: 未找到指定的智能体、会话或执行记录。 security: - bearer: [] components: schemas: AgentChatBody: type: object properties: request: oneOf: - $ref: '#/components/schemas/AgentChatSend' - $ref: '#/components/schemas/AgentChatResume' - $ref: '#/components/schemas/AgentChatRetry' - $ref: '#/components/schemas/AgentChatFollowUp' discriminator: propertyName: action mapping: send: $ref: '#/components/schemas/AgentChatSend' resume: $ref: '#/components/schemas/AgentChatResume' retry: $ref: '#/components/schemas/AgentChatRetry' follow_up: $ref: '#/components/schemas/AgentChatFollowUp' options: type: object properties: xpertId: type: string description: 已发布智能体的 ID。首次调用时提供；续聊会解析会话绑定的智能体。续聊时若提供此字段，必须匹配会话智能体或其可访问的发布版本。 projectId: type: string description: 可选的项目 ID，必须与 request.projectId 及会话项目一致。 language: type: string description: 可选的回复语言，例如 zh-Hans。 timeZone: type: string description: 可选的 IANA 时区，例如 Asia/Shanghai。 context: type: object properties: {} additionalProperties: true description: 可选的运行时上下文，传递给中间件或工具；不能用于覆盖鉴权或授权信息。 description: 公开的调用选项。租户、组织、用户和调用来源由服务端解析；不要在此提交鉴权凭据或内部运行时对象。 required: - request AgentChatSend: type: object properties: action: type: string enum: - send conversationId: type: string description: 会话 ID，取自 on_conversation_start.data.id；首次创建会话时省略。 state: type: object properties: {} additionalProperties: true description: 已发布智能体定义的状态变量。 projectId: type: string description: 可选的项目 ID。必须与已有会话一致；同时提供 options.projectId 时两者也必须一致。 environmentId: type: string description: 可选的环境 ID。 sandboxEnvironmentId: type: string description: 可选的沙箱环境 ID。 message: $ref: '#/components/schemas/AgentChatMessage' required: - action - message AgentChatResume: type: object properties: action: type: string enum: - resume conversationId: type: string description: 已有会话的 ID，取自 on_conversation_start.data.id。此操作必须提供。 state: type: object properties: {} additionalProperties: true description: 已发布智能体定义的状态变量。 target: $ref: '#/components/schemas/AgentChatTarget' decision: type: object properties: type: type: string enum: - confirm - reject payload: description: 可选的决策内容，具体结构由中断要求决定。 required: - type patch: type: object properties: agentKey: type: string description: 发生中断的智能体节点标识。 toolCalls: type: array items: type: object additionalProperties: true update: description: 此中断允许的状态更新内容。 description: 可选的中断编辑内容，须符合实际中断的数据约定。 required: - action - conversationId - target - decision AgentChatRetry: type: object properties: action: type: string enum: - retry conversationId: type: string description: 已有会话的 ID，取自 on_conversation_start.data.id。此操作必须提供。 source: $ref: '#/components/schemas/AgentChatTarget' environmentId: type: string description: 可选的环境 ID。 checkpointId: type: string description: 可选的检查点 ID。 required: - action - conversationId - source AgentChatFollowUp: type: object properties: action: type: string enum: - follow_up conversationId: type: string description: 已有会话的 ID，取自 on_conversation_start.data.id。此操作必须提供。 state: type: object properties: {} additionalProperties: true description: 已发布智能体定义的状态变量。 mode: type: string enum: - queue - steer description: 将追加消息排队（queue），或引导正在执行的任务（steer）。是否可用取决于当前执行状态。 message: $ref: '#/components/schemas/AgentChatMessage' target: $ref: '#/components/schemas/AgentChatTarget' required: - action - conversationId - mode - message AgentChatMessage: type: object properties: clientMessageId: type: string description: 可选的客户端消息标识。不能假定重复请求会自动去重。 input: type: object properties: input: type: string description: 发送给智能体的用户文本。 model: type: string description: 可选的模型选项 ID，取自该智能体的模型目录，不应自行拼接。 additionalProperties: true description: 用户输入对象。额外字段由已发布智能体的输入定义决定。附件须先上传，再传入文件句柄；不能直接传入浏览器 File 对象。 required: - input AgentChatTarget: type: object properties: aiMessageId: type: string description: 已有会话中的智能体消息 ID。 executionId: type: string description: 已有会话中的执行 ID。 description: 使用中断或失败执行返回的标识，不要自行编造。 securitySchemes: bearer: scheme: bearer bearerFormat: JWT type: http ````