Managed Agent对话接口 - InvokeChat

runtime_name

是

String

参数解释：

Managed Agent对应的运行时名称。格式为managed-{Agent名称}

Agent名称获取方式：

1. 进入AgentArts平台，在左侧导航栏选择“Managed Agents”。

2. 在智能体列表中“智能体名称/ID”处获取智能体名称。

约束限制:

不涉及。

取值范围：

以小写字母开头，以小写字母或数字结尾，可以包含小写字母、数字和中划线，长度为2-48个字符。

默认取值:

不涉及。

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认证具体请参见认证鉴权。

约束限制:

不涉及。

取值范围：

不超过4096个字符。

默认取值:

不涉及。

X-Sdk-Content-Sha256

否

String

参数解释：

如果智能体运行时的入站认证类型为IAM认证时，需要指定该Header头为UNSIGNED-PAYLOAD。

约束限制:

不涉及。

取值范围：

UNSIGNED-PAYLOAD：表示请求体不参与签名校验，适用于IAM认证场景下跳过请求体的SHA256校验

默认取值:

不涉及。

-

是

One of:

• 表4 object

• 表6 object

参数解释：

Managed Agent 对话请求体，根据场景二选一：

• 启动新对话：使用 ManagedAgentStartChatRequestBody

• 恢复被中断的对话：使用 ManagedAgentChatResumeRequestBody

约束限制：

不涉及。

取值范围：

不涉及。

默认取值：

不涉及。

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

参数解释：

对话附件结构体。

约束限制：

不涉及。

取值范围：

不涉及。

默认取值：

不涉及。

url

是

String

参数解释：

对话附件的URL路径。当前支持2种格式的URL。

• 本地文件：如/tmp/requirements.txt。
• HTTP/HTTPS路径：如http://host:port/path/file.pdf。

约束限制：

不涉及。

取值范围：

0-1000个字符。

默认取值：

不涉及。

name

否

String

参数解释：

附件名称。

约束限制：

不涉及。

取值范围：

0-128个字符。

默认取值：

不涉及。

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。

默认取值：

不涉及。

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个字符。

默认取值：

不涉及。

id

String

参数解释：

本次对话对应的请求ID。

取值范围：

0 - 128个字符。

event

String

参数解释：

SSE事件名。

取值范围：

见下表。

data

表10~表37 Object

参数解释：

事件payload，数据格式随event类型不同。

取值范围：

不涉及。

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空闲心跳。

event_type

String

参数解释：

事件类型，固定为chat.delta。

取值范围：

chat.delta。

session_id

String

参数解释：

会话ID。

取值范围：

由英文字母，数字，“-”，“_”组成，不超过64个字符。

content

String

参数解释：

对话响应的增量文本内容。该字段是LLM streaming输出的增量片段，每次事件通常只有几个字符到几十个字符。

取值范围：

0-2048个字符。

request_id

String

参数解释：

本次对话对应的请求ID。

取值范围：

1-128个字符。

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个字符。

event_type

String

参数解释：

事件类型，固定为chat.error。

取值范围：

chat.error。

error

String

参数解释：

错误的详细描述信息。

取值范围：

0-4096个字符。

session_id

String

参数解释：

会话ID。

取值范围：

由英文字母，数字，“-”，“_”组成，不超过64个字符。

request_id

String

参数解释：

本次对话对应的请求ID。

取值范围：

0-128个字符。

event_type

String

参数解释：

事件类型，固定为chat.tool_call。

取值范围：

chat.tool_call

tool_call

表14 Object

参数解释：

工具调用详情。

取值范围：

不涉及。

session_id

String

参数解释：

会话ID。

取值范围：

由英文字母，数字，“-”，“_”组成，不超过64个字符。

request_id

String

参数解释：

本次对话对应的请求ID。

取值范围：

0 - 128个字符。

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个字符。

command

String

参数解释：

Shell命令文本。

取值范围：

1-512个字符。

timeout

Integer

参数解释：

命令超时时间（秒）。

取值范围：

1- 3600。

description

String

参数解释：

命令的可读描述。

取值范围：

0-4096个字符。

file_path

String

参数解释：

要读取的文件绝对路径。

取值范围：

参考linux的文件路径格式。

offset

Integer

参数解释：

要跳过的行数（0 表示从头读取）。

取值范围：

0-1000000。

limit

Integer

参数解释：

最多读取的行数。

取值范围：

0-2000。

file_path

String

参数解释：

要写入的文件绝对路径。

取值范围：

文件路径字符串。

content

String

参数解释：

要写入的完整内容。

取值范围：

1-102400个字符。

file_path

String

参数解释：

目标文件的绝对路径。

取值范围：

文件路径字符串。

old_string

String

参数解释：

要替换的原始文本。空字符串可用于创建新文件。

取值范围：

1-1024个字符。

new_string

String

参数解释：

替换后的文本，必须与old_string不同。

取值范围：

1-1024个字符。

replace_all

Boolean

参数解释：

是否替换文件中所有匹配项。

取值范围：

• true：替换所有匹配项。
• false：替换首个匹配项。

pattern

String

参数解释：

glob模式。如*.py、**/*.js、src/**/*.ts。

取值范围：

1-256个字符。

path

String

参数解释：

搜索目录。

取值范围：

目录路径字符串，省略时默认当前工作目录。

path

String

参数解释：

目录路径。

取值范围：

目录路径字符串。

show_hidden

Boolean

参数解释：

是否显示隐藏文件。

取值范围：

• true：展示隐藏文件。
• false：不展示隐藏文件。

pattern

String

参数解释：

搜索模式（正则表达式）。

取值范围：

正则表达式字符串。

path

String

参数解释：

搜索路径（文件或目录）。

取值范围：

路径字符串，默认当前工作目录。

output_mode

String

参数解释：

输出模式。

取值范围：

• content：显示匹配行内容。
• files_with_matches：仅显示匹配文件名。
• count：显示匹配数量。

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个字符。

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个字符。

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个字符。

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个字符。

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：中断响应。

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：无缓存统计（供应商未返回缓存相关数据）。

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个字符。

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个字符，包含数字，“.”，由“%”结尾。

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个字符。

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个字符。

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工具反问用户。

question

String

参数解释：

问题文本。

取值范围：

1-4096个字符。

multi_select

Boolean

参数解释：

是否允许多选。false为单选，true为多选。

取值范围：

• false：单选。
• true：多选。

header

String

参数解释：

问题简短标签。

取值范围：

0-256个字符。

options

Array of 表34 object

参数解释：

可选选项，无options表示自由输入。

取值范围：

最小数量0，最大数量4。

label

String

参数解释：

选项显示文本。

取值范围：

1-256个字符。

description

String

参数解释：

选项详细说明。

取值范围：

0-4096个字符。

event_type

String

参数解释：

事件类型，固定为chat.reasoning。

取值范围：

chat.reasoning。

session_id

String

参数解释：

会话ID。

取值范围：

由英文字母，数字，“-”，“_”组成，不超过64个字符。

content

String

参数解释：

推理过程文本内容。

取值范围：

0-2048个字符。

request_id

String

参数解释：

本次对话对应的请求ID。

取值范围：

1-128个字符。

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个字符。

request_id

String

参数解释：

本次对话对应的请求ID。

取值范围：

1-128个字符。

session_id

String

参数解释：

会话ID。

取值范围：

由英文字母，数字，“-”，“_”组成，不超过64个字符。

code

Integer

参数解释:

异常错误码。

取值范围:

不涉及。

message

String

参数解释：

错误详细信息。

取值范围：

长度为 1 - 512 个字符。

code

Integer

参数解释:

异常错误码。

取值范围:

不涉及。

message

String

参数解释：

错误详细信息。

取值范围：

长度为 1 - 512 个字符。

code

Integer

参数解释:

异常错误码。

取值范围:

不涉及。

message

String

参数解释：

错误详细信息。

取值范围：

长度为 1 - 512 个字符。

200

智能体调用成功的响应Body体，遵循SSE规范。

401

未授权（认证令牌缺失、无效或已过期）。

404

运行时资源不存在。

500

服务器内部错误。