Skip to main content
当智能体遇到以下两种情况时,会暂停执行并发出特殊事件:需要用户确认的工具调用(权限系统返回 ASK),或标记为外部执行的工具(结果必须来自智能体外部)。两种情况下,都通过向 reply / reply_stream 传回结果事件来恢复智能体。 暂停期间,reply 会返回一条 finished_reasonNone 的等待提示消息:回复处于停靠状态而非结束,在外部结果到达之前,剩余的工具调用不会执行。

用户确认

当权限系统判断某个工具调用需要用户批准时,智能体会发出 RequireUserConfirmEvent 并暂停。
1

接收 RequireUserConfirmEvent

使用 reply_stream 检测暂停。事件结构如下:
str
必填
当前回复的 ID,用于恢复智能体。
list[ToolCallBlock]
必填
等待用户确认的工具调用列表。每个 ToolCallBlock 包含:
2

构建确认结果

为每个待处理的工具调用创建 ConfirmResult,指明是否允许执行。也可以修改工具调用输入或接受建议的权限规则:
3

恢复智能体

UserConfirmResultEvent 传回 replyreply_stream
  • 已确认的工具调用立即执行,智能体继续推理
  • 已拒绝的工具调用会产生大语言模型可见的错误结果,模型可能会换一种方式重试
  • 已接受的规则会持久化到权限引擎中,匹配的未来调用将自动允许,无需再次提示

外部工具执行

当智能体调用 is_external_tool = True 的工具时,会发出 RequireExternalExecutionEvent 并暂停。工具的逻辑在智能体外部运行,通常由人工操作或外部系统执行。
1

接收 RequireExternalExecutionEvent

事件结构如下:
str
必填
当前回复的 ID,用于恢复智能体。
list[ToolCallBlock]
必填
需要外部执行的工具调用列表。每个 ToolCallBlock 包含:
2

外部执行并构建结果

在智能体外部执行操作,并将结果封装为 ToolResultBlock 对象:
3

恢复智能体

传回 ExternalExecutionResultEvent 以恢复智能体:
结果会被注入智能体上下文,推理从中断处继续。
如果多个工具调用都需要外部交互,而只传回了部分确认或执行结果,智能体不会为尚未确认或执行的工具调用重新发出请求事件。
构建交互式界面时使用 reply_stream:它可以实时检测暂停事件并立即提示用户。以编程方式处理事件的自动化流程则使用 reply