# Managed Agent对话接口 - InvokeChat #### 功能介绍 该接口是Managed Agent的核心对话接口，用户可以使用该接口与已经部署好的Managed Agent进行对话，对话响应使用SSE流式返回，部署Managed Agent请参见[部署Managed Agent](https://support.huaweicloud.com/managedagents-agentarts/agentarts_13_0002.html)。 - **适用场景：** 流式对话、中断恢复、带文件附件的对话。 - **接口约束：** 流式响应持续推送事件直至 chat.final / chat.error / chat.interrupt_result 终态事件 当 Agent 需要用户输入时推送 chat.ask_user_question 事件，SSE 流结束，需通过本接口恢复 空闲超过 10 秒时推送 keepalive 心跳帧 #### 调用方法 请参见[如何调用API](https://support.huaweicloud.com/api-agentarts/agentarts_07_0003.html)。 #### 授权信息 当前API调用无需身份策略权限。 #### URI POST /runtimes/{runtime_name}/invocations/v1/chat/completions 表1路径参数 | 参数 | 是否必选 | 参数类型 | 描述 | |:---|:---|:---|:---| | runtime_name | 是 | String | **参数解释**： Managed Agent对应的运行时名称。格式为managed-{Agent名称} Agent名称获取方式： 1. 进入AgentArts平台，在左侧导航栏选择"Managed Agents"。 2. 在智能体列表中"智能体名称/ID"处获取智能体名称。 **约束限制**: 不涉及。 **取值范围**： 以小写字母开头，以小写字母或数字结尾，可以包含小写字母、数字和中划线，长度为2-48个字符。 **默认取值**: 不涉及。 | #### 请求参数 表2请求Header参数 | 参数 | 是否必选 | 参数类型 | 描述 | |:---|:---|:---|:---| | X-Hw-Agentarts-Session-Id | 是 | String | **参数解释**： 会话ID，每个会话的唯一标识符。用户可将会话ID设置为任意符合下述字符集要求的字符串，例如"123e4567e89b12d3a456426614174000"，无需在其他地方获取。 **约束限制**: 不涉及。 **取值范围**： 由英文字母，数字，"-"，"_"组成，不超过64个字符。 **默认取值**: 不涉及。 | | X-Hw-Agentgateway-User-Id | 否 | String | **参数解释**： 本次智能体运行时调用对应的用户唯一ID，用于标识此次调用的用户身份，用户可自行设置用户ID，需符合取值范围的字符要求，例如"123e4567e89b12d3a456426614174000"，无需在其他地方获取。 **约束限制**: 不涉及。 **取值范围**： 由英文字母，数字，"-"，"_"组成，不超过128个字符。 **默认取值**: 不涉及。 | | Authorization | 是 | String | **参数解释**： 本次智能体运行时调用对应的身份认证凭据。需要根据实际的智能体运行时的入站身份认证方式获取对应的身份认证凭据。 API Key认证、IAM认证及OAuth 2.0认证具体请参见[认证鉴权](https://support.huaweicloud.com/api-agentarts/agentarts_07_0005.html)。 **约束限制**: 不涉及。 **取值范围**： 不超过4096个字符。 **默认取值**: 不涉及。 | | X-Sdk-Content-Sha256 | 否 | String | **参数解释**： 如果智能体运行时的入站认证类型为IAM认证时，需要指定该Header头为UNSIGNED-PAYLOAD。 **约束限制**: 不涉及。 **取值范围**： UNSIGNED-PAYLOAD：表示请求体不参与签名校验，适用于IAM认证场景下跳过请求体的SHA256校验 **默认取值**: 不涉及。 | 表3请求Body参数 | 参数 | 是否必选 | 参数类型 | 描述 | |:---|:---|:---|:---| | - | 是 | One of: - [表4] object - [表6] object | **参数解释**： Managed Agent 对话请求体，根据场景二选一： - 启动新对话：使用 ManagedAgentStartChatRequestBody - 恢复被中断的对话：使用 ManagedAgentChatResumeRequestBody **约束限制**： 不涉及。 **取值范围**： 不涉及。 **默认取值**： 不涉及。 | 表4ManagedAgentStartChatRequestBody | 参数 | 是否必选 | 参数类型 | 描述 | |:---|:---|:---|:---| | query | 否 | String | **参数解释**： 与Agent对话的用户输入文本。如果本次请求用于恢复之前被中断的对话，该字段非必填。 **约束限制**： 该字段的长度上限受到模型的上下文窗口大小的限制，具体的限制以使用的具体模型为准。 **取值范围**： 0 - 1048576个字符 **默认取值**： 不涉及。 | | skills | 否 | Array of String | **参数解释**： 与Agent对话需要使用的技能列表。 **约束限制**： 不涉及。 **取值范围**： 必须是Managed Agent已经配置的技能的子集。每个元素1-64个字符，最小数量0，最大数量50。 **默认取值**： 不涉及。 | | project_dir | 否 | String | **参数解释**： 工作区目录的绝对路径。 **约束限制**： 不允许使用/根目录，不允许出现\\x00、\\n、\\r、;、\|、\&、$、\\\\、!、{、}\`等特殊字符。 **取值范围**： 0 - 1000个字符 **默认取值**： 不涉及。 | | files | 否 | [表5] object | **参数解释**： 对话附件结构体。 **约束限制**： 不涉及。 **取值范围**： 不涉及。 **默认取值**： 不涉及。 | 表5ManagedAgentFileRef | 参数 | 是否必选 | 参数类型 | 描述 | |:---|:---|:---|:---| | url | 是 | String | **参数解释**： 对话附件的URL路径。当前支持2种格式的URL。 - 本地文件：如/tmp/requirements.txt。 - HTTP/HTTPS路径：如http://host:port/path/file.pdf。 **约束限制**： 不涉及。 **取值范围**： 0-1000个字符。 **默认取值**： 不涉及。 | | name | 否 | String | **参数解释**： 附件名称。 **约束限制**： 不涉及。 **取值范围**： 0-128个字符。 **默认取值**： 不涉及。 | 表6ManagedAgentChatResumeRequestBody | 参数 | 是否必选 | 参数类型 | 描述 | |:---|:---|:---|:---| | request_id | 否 | String | **参数解释**： 需要恢复的对话对应的请求ID，可以从上一次对话的响应中找到ask_user_question事件对应的request_id字段。 **约束限制**： 不涉及。 **取值范围**： 0 - 128个字符 **默认取值**： 不涉及。 | | status | 否 | String | **参数解释**： 用户回答上一个请求的问题的状态，如果是answered，则请求需要包含answers字段。 **约束限制**： 不涉及。 **取值范围**： answered：已回答。 skipped：已跳过。 **默认取值**： answered | | source | 否 | String | **参数解释**： 问题来源，对应上一次对话响应中ask_user_question事件的source字段。 **约束限制**： 不涉及。 **取值范围**： permission_interrupt：工具权限审批。 confirm_interrupt：操作确认审批。 ask_user_interrupt：Agent反问。 **默认取值**： 不涉及。 | | answers | 否 | Array of [表7] object | **参数解释**： 本次恢复对话需要回答的问题答案列表，如果本次请求status为answered，则该字段需要包含至少一个元素。 **约束限制**： 不涉及。 **取值范围**： 最小数量0，最大数量4。 **默认取值**： 不涉及。 | 表7ManagedAgentChatResumeAnswer | 参数 | 是否必选 | 参数类型 | 描述 | |:---|:---|:---|:---| | selected_options | 是 | Array of String | **参数解释**： 针对Agent反问选择的选项文本，如果上一次对话响应中ask_user_question事件的multi_select字段为true，则该字段支持多个选项，否则仅支持一个选项。 **约束限制**： 不涉及。 **取值范围**： 需要上一次对话响应中ask_user_question事件的options字段的子集。每个选项1-512个字符，最小数量0，最大数量50。 **默认取值**： 不涉及。 | | custom_input | 否 | String | **参数解释**： 针对Agent反问提供的额外的答案说明。 **约束限制**： 该字段的长度上限受到模型的上下文窗口大小的限制，具体的限制以使用的具体模型为准。 **取值范围**： 0-1048576个字符。 **默认取值**： 不涉及。 | #### 响应参数 **状态码：200** 响应体遵循SSE（Server-Sent Events）规范。一次完整的响应包含多个SSE事件，每条事件格式为id/event/data三行。 表8SSE响应体参数 | 参数 | 参数类型 | 描述 | |:---|:---|:---| | id | String | **参数解释**： 本次对话对应的请求ID。 **取值范围**： 0 - 128个字符。 | | event | String | **参数解释**： SSE事件名。 **取值范围**： 见下表。 | | data | [表10]\~[表37] Object | **参数解释**： 事件payload，数据格式随event类型不同。 **取值范围**： 不涉及。 | 表9event取值范围 | 事件类型 | 描述 | |:---|:---| | chat.delta | 增量文本片段。 | | chat.final | 本轮对话成功结束。 | | chat.error | 本轮对话异常结束。 | | chat.tool_call | Agent发起工具调用。 | | chat.tool_update | 工具调用状态更新。 | | chat.tool_result | 工具调用成功结束。 | | chat.processing_status | 对话轮次开始/结束。 | | chat.usage_metadata | 单次LLM调用Token使用量统计。 | | chat.usage_summary | 本轮对话Token使用量统计。 | | context.usage | 上下文窗口使用量统计。 | | chat.interrupt_result | 用户中断。 | | chat.ask_user_question | Agent发起反问。 | | chat.reasoning | Agent推理/思考。 | | chat.invocation_paused | Agent执行暂停。 | | keepalive | Agent空闲心跳。 | 表10data（event为chat.delta时） | 参数 | 参数类型 | 描述 | |:---|:---|:---| | event_type | String | **参数解释**： 事件类型，固定为chat.delta。 **取值范围**： chat.delta。 | | session_id | String | **参数解释**： 会话ID。 **取值范围**： 由英文字母，数字，"-"，"_"组成，不超过64个字符。 | | content | String | **参数解释**： 对话响应的增量文本内容。该字段是LLM streaming输出的增量片段，每次事件通常只有几个字符到几十个字符。 **取值范围**： 0-2048个字符。 | | request_id | String | **参数解释**： 本次对话对应的请求ID。 **取值范围**： 1-128个字符。 | 表11data（event为chat.final时） | 参数 | 参数类型 | 描述 | |:---|:---|:---| | event_type | String | **参数解释**： 事件类型，固定为chat.final。 **取值范围**： chat.final。 | | is_complete | Boolean | **参数解释**： 标识本轮对话是否完整结束。固定为true。 **取值范围**： true。 | | final_mode | String | **参数解释**： chat.final事件的前端UI渲染模式，指示前端如何展示本次final内容。 **取值范围**： - patch_segment：覆写当前/匹配分段。 - replace_turn：用final替换本轮全部助手气泡。 - append：追加新气泡。 | | session_id | String | **参数解释**： 会话ID。 **取值范围**： 由英文字母，数字，"-"，"_"组成，不超过64个字符。 | | content | String | **参数解释**： 完整响应文本（可能为空，实际内容已在chat.delta中推送）。 **取值范围**： 0-2048个字符。 | | request_id | String | **参数解释**： 本次对话对应的请求ID。 **取值范围**： 0-128个字符。 | 表12data（event为chat.error时） | 参数 | 参数类型 | 描述 | |:---|:---|:---| | event_type | String | **参数解释**： 事件类型，固定为chat.error。 **取值范围**： chat.error。 | | error | String | **参数解释**： 错误的详细描述信息。 **取值范围**： 0-4096个字符。 | | session_id | String | **参数解释**： 会话ID。 **取值范围**： 由英文字母，数字，"-"，"_"组成，不超过64个字符。 | | request_id | String | **参数解释**： 本次对话对应的请求ID。 **取值范围**： 0-128个字符。 | 表13data（event为chat.tool_call时） | 参数 | 参数类型 | 描述 | |:---|:---|:---| | event_type | String | **参数解释**： 事件类型，固定为chat.tool_call。 **取值范围**： chat.tool_call | | tool_call | [表14] Object | **参数解释**： 工具调用详情。 **取值范围**： 不涉及。 | | session_id | String | **参数解释**： 会话ID。 **取值范围**： 由英文字母，数字，"-"，"_"组成，不超过64个字符。 | | request_id | String | **参数解释**： 本次对话对应的请求ID。 **取值范围**： 0 - 128个字符。 | 表14tool_call | 参数 | 参数类型 | 描述 | |:---|:---|:---| | name | String | **参数解释**： 发起调用的工具名称。 **取值范围**： read_file：读取文件 write_file：写入文件 edit_file：精确字符串替换编辑已有文件 bash：执行Shell命令 list_files：列出目录内容 glob：使用glob模式查找文件 grep：在文件中搜索内容，支持正则表达式 | | tool_call_id | String | **参数解释**： 工具调用唯一ID。 **取值范围**： 0 - 128个字符。 | | arguments | One of： - [表15] object - [表16] object - [表17] object - [表18] object - [表19] object - [表20] object - [表21] object | **参数解释**： 工具调用使用的所有参数。该参数是动态键值对，随工具不同而不同，实际使用时以工具定义为准。 **取值范围**： 不涉及。 | | display_name | String | **参数解释**： 工具调用的可读展示名称，用于前端展示。 **取值范围**： 0 - 256个字符。 | 表15BashArguments | 参数 | 参数类型 | 描述 | |:---|:---|:---| | command | String | **参数解释**： Shell命令文本。 **取值范围**： 1-512个字符。 | | timeout | Integer | **参数解释**： 命令超时时间（秒）。 **取值范围**： 1- 3600。 | | description | String | **参数解释**： 命令的可读描述。 **取值范围**： 0-4096个字符。 | 表16ReadFileArguments | 参数 | 参数类型 | 描述 | |:---|:---|:---| | file_path | String | **参数解释**： 要读取的文件绝对路径。 **取值范围**： 参考linux的文件路径格式。 | | offset | Integer | **参数解释**： 要跳过的行数（0 表示从头读取）。 **取值范围**： 0-1000000。 | | limit | Integer | **参数解释**： 最多读取的行数。 **取值范围**： 0-2000。 | 表17WriteFileArguments | 参数 | 参数类型 | 描述 | |:---|:---|:---| | file_path | String | **参数解释**： 要写入的文件绝对路径。 **取值范围**： 文件路径字符串。 | | content | String | **参数解释**： 要写入的完整内容。 **取值范围**： 1-102400个字符。 | 表18EditFileArguments | 参数 | 参数类型 | 描述 | |:---|:---|:---| | file_path | String | **参数解释**： 目标文件的绝对路径。 **取值范围**： 文件路径字符串。 | | old_string | String | **参数解释**： 要替换的原始文本。空字符串可用于创建新文件。 **取值范围**： 1-1024个字符。 | | new_string | String | **参数解释**： 替换后的文本，必须与old_string不同。 **取值范围**： 1-1024个字符。 | | replace_all | Boolean | **参数解释**： 是否替换文件中所有匹配项。 **取值范围**： - true：替换所有匹配项。 - false：替换首个匹配项。 | 表19GlobArguments | 参数 | 参数类型 | 描述 | |:---|:---|:---| | pattern | String | **参数解释**： glob模式。如\*.py、\*\*/\*.js、src/\*\*/\*.ts。 **取值范围**： 1-256个字符。 | | path | String | **参数解释**： 搜索目录。 **取值范围**： 目录路径字符串，省略时默认当前工作目录。 | 表20ListFilesArguments | 参数 | 参数类型 | 描述 | |:---|:---|:---| | path | String | **参数解释**： 目录路径。 **取值范围**： 目录路径字符串。 | | show_hidden | Boolean | **参数解释**： 是否显示隐藏文件。 **取值范围**： - true：展示隐藏文件。 - false：不展示隐藏文件。 | 表21GrepArguments | 参数 | 参数类型 | 描述 | |:---|:---|:---| | pattern | String | **参数解释**： 搜索模式（正则表达式）。 **取值范围**： 正则表达式字符串。 | | path | String | **参数解释**： 搜索路径（文件或目录）。 **取值范围**： 路径字符串，默认当前工作目录。 | | output_mode | String | **参数解释**： 输出模式。 **取值范围**： - content：显示匹配行内容。 - files_with_matches：仅显示匹配文件名。 - count：显示匹配数量。 | 表22data（event为chat.tool_update时） | 参数 | 参数类型 | 描述 | |:---|:---|:---| | event_type | String | **参数解释**： 事件类型，固定为chat.tool_update。 **取值范围**： chat.tool_update。 | | tool_name | String | **参数解释**： 发起调用的工具名称。 **取值范围**： read_file/write_file/edit_file/bash/list_files/glob/grep | | arguments | One of： - [表15] object - [表16] object - [表17] object - [表18] object - [表19] object - [表20] object - [表21] object | **参数解释**： 工具调用使用的所有参数。 **取值范围**： 不涉及。 | | tool_call_id | String | **参数解释**： 工具调用唯一ID。 **取值范围**： 0-128个字符。 | | status | String | **参数解释**： 工具执行状态。 **取值范围**： - in_progress：工具开始执行中。 - error：工具执行出错。 | | session_id | String | **参数解释**： 会话ID。 **取值范围**： 由英文字母，数字，"-"，"_"组成，不超过64个字符。 | | request_id | String | **参数解释**： 本次对话对应的请求ID。 **取值范围**： 0-128个字符。 | 表23data（event为chat.tool_result时） | 参数 | 参数类型 | 描述 | |:---|:---|:---| | event_type | String | **参数解释**： 事件类型，固定为chat.tool_result。 **取值范围**： chat.tool_result。 | | result | String | **参数解释**： 工具执行结果（序列化后的字符串）。 **取值范围**： 1-4096个字符。 | | tool_name | String | **参数解释**： 发起调用的工具名称。 **取值范围**： read_file/write_file/edit_file/bash/list_files/glob/grep。 | | tool_call_id | String | **参数解释**： 工具调用唯一ID。 **取值范围**： 0-128个字符。 | | session_id | String | **参数解释**： 会话ID。 **取值范围**： 由英文字母，数字，"-"，"_"组成，不超过64个字符。 | | request_id | String | **参数解释**： 本次对话对应的请求ID。 **取值范围**： 0-128个字符。 | 表24data（event为chat.processing_status时） | 参数 | 参数类型 | 描述 | |:---|:---|:---| | event_type | String | **参数解释**： 事件类型，固定为chat.processing_status。 **取值范围**： chat.processing_status。 | | is_processing | Boolean | **参数解释**： 本轮次是否正在执行。 **取值范围**： - true：开始执行。 - false：结束执行。 | | is_complete | Boolean | **参数解释**： 本轮次是否结束执行。 **取值范围**： - true：结束执行。 - false：未结束执行。 | | session_id | String | **参数解释**： 会话ID。 **取值范围**： 由英文字母，数字，"-"，"_"组成，不超过64个字符。 | | request_id | String | **参数解释**： 本次对话对应的请求ID。 **取值范围**： 0-128个字符。 | 表25data（event为chat.usage_metadata时） | 参数 | 参数类型 | 描述 | |:---|:---|:---| | event_type | String | **参数解释**： 事件类型，固定为chat.usage_metadata。 **取值范围**： chat.usage_metadata。 | | metadata | [表26] Object | **参数解释**： 用量元数据包装对象，包含usage_metadata（Token统计明细）、延迟指标和结果类型。 **取值范围**： 不涉及。 | | session_id | String | **参数解释**： 会话ID。 **取值范围**： 由英文字母，数字，"-"，"_"组成，不超过64个字符。 | | request_id | String | **参数解释**： 本次对话对应的请求ID。 **取值范围**： 0-128个字符。 | 表26metadata | 参数 | 参数类型 | 描述 | |:---|:---|:---| | usage_metadata | [表27] object | **参数解释**： LLM调用的Token用量明细，来源于模型API响应的usage_metadata字段。包含input_tokens、output_tokens、total_tokens、cache_tokens、cache_read_tokens、cache_miss_tokens、cache_write_tokens、cache_status、cache_source、cache_authoritative、reasoning_tokens、model_name、code、err_msg等字段。 **取值范围**： 不涉及。 | | total_latency_ms | Number | **参数解释**： 本次LLM调用总延迟（毫秒）。 **取值范围**： \[0, 600000\]。 | | ttft_ms | Number | **参数解释**： Time To First Token，首Token延迟（毫秒）。 **取值范围**： \[0, 600000\]。 | | tpot_ms | Number | **参数解释**： Time Per Output Token，平均每个输出Token的生成耗时（毫秒）。 **取值范围**： \[0, 600000\]。 | | result_type | String | **参数解释**： LLM响应结果类型。 **取值范围**： - answer：LLM正常生成回复。 - text：LLM返回纯文本输出。 - interrupt：中断响应。 | 表27UsageMetadata | 参数 | 参数类型 | 描述 | |:---|:---|:---| | code | Integer | **参数解释**： 模型API返回码，0表示成功。 **取值范围**： 0-1000000。 | | err_msg | String | **参数解释**： 模型API错误信息，成功时为空字符串。 **取值范围**： 0-4096个字符。 | | model_name | String | **参数解释**： 实际使用的模型名称（如GLM-5.1、gpt-4等）。 **取值范围**： 0-128个字符。 | | input_tokens | Integer | **参数解释**： 输入 Token 数（含 Prompt + 历史 + 工具描述等）。 **取值范围**： 0-1000000。 | | output_tokens | Integer | **参数解释**： 输出Token数（LLM生成的回复）。 **取值范围**： 0-1000000。 | | total_tokens | Integer | **参数解释**： 总 Token 数（input_tokens + output_tokens）。 **取值范围**： 0-1000000。 | | cache_read_tokens | Integer | **参数解释**： 从缓存读取的Token数（Prompt Caching命中部分，不计费或低费率）。 **取值范围**： 0-1000000。 | | cache_miss_tokens | Integer | **参数解释**： 缓存未命中的 Token 数。 **取值范围**： 0-1000000。 | | cache_write_tokens | Integer | **参数解释**： 写入缓存的Token数。 **取值范围**： 0-1000000。 | | cache_source | String | **参数解释**： 缓存数据来源，如果该字段为null，表示供应商未返回缓存相关明细数据。 **取值范围**： provider_usage：来自供应商Usage统计。 | | cache_authoritative | Boolean | **参数解释**： 缓存统计是否为权威值（供应商直接返回）。 **取值范围**： - true：表示cache_read_tokens等缓存统计字段是权威的，可信赖。 - false：表示cache_read_tokens等缓存统计字段可能是从语义不明确的cache_tokens字段推断的，不应作为计费依据。 | | reasoning_tokens | Integer | **参数解释**： 推理Token数（模型内部推理过程消耗的Token，不直接输出给用户）。 **取值范围**： 0-1000000。 | | total_latency | Number | **参数解释**： 本次LLM调用总延迟（毫秒），从请求发出到响应完成的总耗时。 **取值范围**： \[0, 600000\]。 | | cache_tokens | Integer | **参数解释**： 缓存命中的Token总数。部分供应商返回此字段作为缓存命中的汇总值，与cache_read_tokens含义一致或为其超集。cache_authoritative=false时，此字段可能是cache_read_tokens的推断来源。 **取值范围**： 0-1000000。 | | cache_status | String | **参数解释**： 缓存统计状态。 **取值范围**： - observed：缓存统计来自供应商权威返回（cache_authoritative=true 时对应）。 - estimated：缓存统计为估算值（cache_authoritative=false 时对应）。 - none：无缓存统计（供应商未返回缓存相关数据）。 | 表28data（event为chat.usage_summary时） | 参数 | 参数类型 | 描述 | |:---|:---|:---| | event_type | String | **参数解释**： 事件类型，固定为chat.usage_summary。 **取值范围**： chat.usage_summary。 | | session_id | String | **参数解释**： 会话ID。 **取值范围**： 由英文字母，数字，"-"，"_"组成，不超过64个字符。 | | usage | [表29] object | **参数解释**： 整轮对话累计的Token用量和费用汇总。 **取值范围**： 不涉及。 | | model | String | **参数解释**： 实际使用的模型名称。 **取值范围**： 0-128个字符。 | | usage_percent | Number | **参数解释**： 上下文窗口使用百分比。 **取值范围**： \[0-100\]。 | | context_window_tokens | Integer | **参数解释**： 上下文窗口总Token上限。 **取值范围**： 0-1000000。 | | request_id | String | **参数解释**： 本次对话对应的请求ID。 **取值范围**： 0-128个字符。 | 表29UsageSummary | 参数 | 参数类型 | 描述 | |:---|:---|:---| | input_tokens | Integer | **参数解释**： 本轮所有LLM调用的输入Token累计总数。 **取值范围**： 0-1000000。 | | output_tokens | Integer | **参数解释**： 本轮所有LLM调用的输出Token累计总数。 **取值范围**： 0-1000000。 | | total_tokens | Integer | **参数解释**： 本轮所有LLM调用的总Token累计总数（input+output）。 **取值范围**： 0-1000000。 | | cache_tokens | Integer | **参数解释**： 本轮缓存命中的Token累计总数。 **取值范围**： 0-1000000。 | | cache_hit_rate | String | **参数解释**： 缓存命中率（百分比字符串），等于cache_tokens / input_tokens，如"98.2%"。 **取值范围**： 0-10个字符，包含数字，"."，由"%"结尾。 | 表30data（event为context.usage时） | 参数 | 参数类型 | 描述 | |:---|:---|:---| | event_type | String | **参数解释**： 事件类型，固定为chat.usage。 **取值范围**： chat.usage。 | | rate | Number | **参数解释**： 使用百分比。 **取值范围**： \[0-100\]。 | | context_max | Integer | **参数解释**： 上下文窗口总Token上限。 **取值范围**： 0-1000000。 | | tokens_used | Integer | **参数解释**： 已用Token数。 **取值范围**： 0-1000000。 | | session_id | String | **参数解释**： 会话ID。 **取值范围**： 由英文字母，数字，"-"，"_"组成，不超过64个字符。 | | request_id | String | **参数解释**： 本次对话对应的请求ID。 **取值范围**： 0-128个字符。 | 表31data（event为chat.interrupt_result时） | 参数 | 参数类型 | 描述 | |:---|:---|:---| | event_type | String | **参数解释**： 事件类型，固定为chat.interrupt_result。 **取值范围**： chat.interrupt_result。 | | intent | String | **参数解释**： 用户中断的中断意图。 **取值范围**： - cancel：取消当前任务，原SSE流关闭。 - supplement：取消当前任务但保留上下文，原SSE流关闭。 - pause：暂停ReAct循环，原SSE流保持打开。 - resume：恢复被pause暂停的ReAct循环，原SSE流继续推送。 | | success | Boolean | **参数解释**： 中断是否成功。 **取值范围**： - true：中断成功。 - false：中断失败。 | | message | String | **参数解释**： 中断结果描述。 **取值范围**： 0-4096个字符。 | 表32data（event为chat.ask_user_question时） | 参数 | 参数类型 | 描述 | |:---|:---|:---| | event_type | String | **参数解释**： 事件类型，固定为chat.ask_user_question。 **取值范围**： chat.ask_user_question。 | | request_id | String | **参数解释**： 中断请求ID，恢复时回传。 **取值范围**： 0-128个字符。 | | session_id | String | **参数解释**： 会话ID。 **取值范围**： 由英文字母，数字，"-"，"_"组成，不超过64个字符。 | | questions | Array of [表33] object | **参数解释**： 结构化问题列表。 **取值范围**： 最小数量1，最大数量4。 | | source | String | **参数解释**： 中断来源。 **取值范围**： - permission_interrupt：工具权限审批。 - confirm_interrupt：控制类工具确认。 - ask_user_interrupt：LLM主动调用ask_user工具反问用户。 | 表33QuestionItem | 参数 | 参数类型 | 描述 | |:---|:---|:---| | question | String | **参数解释**： 问题文本。 **取值范围**： 1-4096个字符。 | | multi_select | Boolean | **参数解释**： 是否允许多选。false为单选，true为多选。 **取值范围**： - false：单选。 - true：多选。 | | header | String | **参数解释**： 问题简短标签。 **取值范围**： 0-256个字符。 | | options | Array of [表34] object | **参数解释**： 可选选项，无options表示自由输入。 **取值范围**： 最小数量0，最大数量4。 | 表34QuestionOption | 参数 | 参数类型 | 描述 | |:---|:---|:---| | label | String | **参数解释**： 选项显示文本。 **取值范围**： 1-256个字符。 | | description | String | **参数解释**： 选项详细说明。 **取值范围**： 0-4096个字符。 | 表35data（event为chat.reasoning时） | 参数 | 参数类型 | 描述 | |:---|:---|:---| | event_type | String | **参数解释**： 事件类型，固定为chat.reasoning。 **取值范围**： chat.reasoning。 | | session_id | String | **参数解释**： 会话ID。 **取值范围**： 由英文字母，数字，"-"，"_"组成，不超过64个字符。 | | content | String | **参数解释**： 推理过程文本内容。 **取值范围**： 0-2048个字符。 | | request_id | String | **参数解释**： 本次对话对应的请求ID。 **取值范围**： 1-128个字符。 | 表36data（event为chat.invocation_paused时） | 参数 | 参数类型 | 描述 | |:---|:---|:---| | event_type | String | **参数解释**： 事件类型，固定为chat.invocation_paused。 **取值范围**： chat.invocation_paused。 | | awaiting_user_input | Boolean | **参数解释**： 固定true，标识等待用户输入。 **取值范围**： true。 | | request_id | String | **参数解释**： 中断请求ID，恢复时回传。 **取值范围**： 0-128个字符。 | | session_id | String | **参数解释**： 会话ID。 **取值范围**： 由英文字母，数字，"-"，"_"组成，不超过64个字符。 | 表37data（event为keepalive时） | 参数 | 参数类型 | 描述 | |:---|:---|:---| | request_id | String | **参数解释**： 本次对话对应的请求ID。 **取值范围**： 1-128个字符。 | | session_id | String | **参数解释**： 会话ID。 **取值范围**： 由英文字母，数字，"-"，"_"组成，不超过64个字符。 | **状态码：401** 表38响应Body参数 | 参数 | 参数类型 | 描述 | |:---|:---|:---| | code | Integer | **参数解释**: 异常错误码。 **取值范围**: 不涉及。 | | message | String | **参数解释**： 错误详细信息。 **取值范围**： 长度为 1 - 512 个字符。 | **状态码：404** 表39响应Body参数 | 参数 | 参数类型 | 描述 | |:---|:---|:---| | code | Integer | **参数解释**: 异常错误码。 **取值范围**: 不涉及。 | | message | String | **参数解释**： 错误详细信息。 **取值范围**： 长度为 1 - 512 个字符。 | **状态码：500** 表40响应Body参数 | 参数 | 参数类型 | 描述 | |:---|:---|:---| | code | Integer | **参数解释**: 异常错误码。 **取值范围**: 不涉及。 | | message | String | **参数解释**： 错误详细信息。 **取值范围**： 长度为 1 - 512 个字符。 | #### 请求示例 启动Agent对话, gateway_domain为运行时的访问域名，可以在智能体运行时的运行时详情页面中获取 ``` POST https://{gateway_domain}/runtimes/{runtime_name}/invocations/v1/chat/completions { "query" : "帮我分析当前目录下代码是否存在性能问题", "project_dir" : "/home/mnt/myproject" } ``` #### 响应示例 **状态码：200** ``` event: web.response data: {"accepted": true, "session_id": "sess-001"} id: req-001 event: chat.processing_status data: {"session_id": "sess-001", "request_id": "req-001", "is_processing": true, "is_complete": false} id: req-001 event: chat.reasoning data: {"session_id": "sess-001", "content": "用户要求分析代码性能，我需要先读取文件内容，然后逐函数分析可能的性能瓶颈。", "request_id": "req-001"} id: req-001 event: chat.tool_call data: {"tool_call": {"name": "read_file", "tool_call_id": "call-001", "arguments": {"file_path": "/src/auth.py"}, "display_name": "读取 auth.py"}, "session_id": "sess-001", "request_id": "req-001"} id: req-001 event: chat.tool_update data: {"tool_name": "read_file", "tool_call_id": "call-001", "arguments": {"file_path": "/src/auth.py"}, "status": "in_progress", "session_id": "sess-001", "request_id": "req-001"} id: req-001 event: chat.tool_result data: {"result": "def login(username, password):\n import hashlib\n hashed = hashlib.md5(password.encode()).hexdigest()\n ...", "tool_name": "read_file", "tool_call_id": "call-001", "session_id": "sess-001", "request_id": "req-001"} id: req-001 event: chat.reasoning data: {"session_id": "sess-001", "content": "分析完成。login 函数使用了 MD5 哈希（性能尚可但安全性不足），数据库查询是同步阻塞的 requests.get，这是主要性能瓶颈。", "request_id": "req-001"} id: req-001 event: chat.delta data: {"session_id": "sess-001", "content": "分析完成，", "request_id": "req-001"} id: req-001 event: chat.delta data: {"session_id": "sess-001", "content": "发现以下性能瓶颈：\n\n", "request_id": "req-001"} id: req-001 event: chat.delta data: {"session_id": "sess-001", "content": "**1. 同步数据库查询**\n", "request_id": "req-001"} id: req-001 event: chat.delta data: {"session_id": "sess-001", "content": "`login()` 函数中使用 `requests.get()` 同步等待数据库响应，阻塞事件循环。\n\n", "request_id": "req-001"} id: req-001 event: chat.delta data: {"session_id": "sess-001", "content": "**2. MD5 哈希**\n", "request_id": "req-001"} id: req-001 event: chat.delta data: {"session_id": "sess-001", "content": "密码哈希使用 MD5，安全性不足，建议改用 bcrypt。", "request_id": "req-001"} id: req-001 event: chat.usage_metadata data: {"metadata": {"usage_metadata": {"input_tokens": 5200, "output_tokens": 138, "total_tokens": 5338, "cache_tokens": 4500, "cache_read_tokens": 4500, "cache_miss_tokens": null, "cache_write_tokens": null, "cache_status": "observed", "cache_source": "provider_usage", "cache_authoritative": true, "reasoning_tokens": 1, "model_name": "GLM-5.1", "input_cost": 0.008, "output_cost": 0.004, "total_cost": 0.012, "code": 0, "err_msg": ""}, "total_latency_ms": 2100.5, "ttft_ms": 850.3, "tpot_ms": 26.9, "result_type": "answer"}, "session_id": "sess-001", "request_id": "req-001"} id: req-001 event: chat.usage_summary data: {"session_id": "sess-001", "usage": {"input_tokens": 5200, "output_tokens": 138, "total_tokens": 5338, "cache_tokens": 4500, "cache_hit_rate": "86.5%", "total_cost": 0.012}, "model": "GLM-5.1", "usage_percent": 2.6, "context_window_tokens": 202752, "request_id": "req-001"} id: req-001 event: context.usage data: {"rate": 2.6, "context_max": 202752, "tokens_used": 5338, "session_id": "sess-001"} id: req-001 event: chat.final data: {"session_id": "sess-001", "content": "", "request_id": "req-001"} ``` #### 状态码 | 状态码 | 描述 | |:---|:---| | 200 | 智能体调用成功的响应Body体，遵循SSE规范。 | | 401 | 未授权（认证令牌缺失、无效或已过期）。 | | 404 | 运行时资源不存在。 | | 500 | 服务器内部错误。 | #### 错误码 请参见[错误码](https://support.huaweicloud.com/api-agentarts/ErrorCode.html)。