工具确认流程

部分敏感工具（如画布修改、角色切换）在执行前需要用户明确批准。本节详细描述这一交互流程。

需要确认的工具

工具名称	操作
CreateCanvasElementsFunction	在画布上创建节点/边
UpdateCanvasElementsFunction	修改画布元素
DeleteCanvasElementsFunction	删除画布元素
SwitchCharacterFunction	切换当前 AI 角色
AddNodeGroupElementsFunction	向节点组添加元素
RemoveNodeGroupElementsFunction	从节点组移除元素

确认状态

工具调用的 confirmation_state 字段标识当前状态：

状态	含义	用户行为
none	无需确认 / 已处理	无需操作
pending	等待用户批准	显示确认弹窗，用户选择接受或拒绝
awaiting_input	工具已执行，等待用户输入	显示输入框，用户通过 ToolMessage 回复

自动接受模式

对话的 accepting_edits 字段控制确认行为：

值	行为
false（默认）	敏感工具需要用户确认
true	所有工具自动执行，跳过确认

通过 PATCH /api/v1/conversations/{id} 修改：

{ "accepting_edits": true }

完整交互时序

场景一：用户接受

场景二：用户拒绝

场景三：混合工具调用（部分需确认）

AI 可能同时调用多个工具，其中部分需要确认：

等待用户输入（awaiting_input）

某些工具（如 AskUserFunction）执行后需要用户提供额外信息：

关键区别：

• pending → 工具未执行，用户通过 tool_confirmation_response 消息批准/拒绝
• awaiting_input → 工具已执行，用户通过 append_message（role=tool）提供输入

确认消息格式

客户端发送

{
  "type": "tool_confirmation_response",
  "payload": {
    "tool_call_id": "call_abc123",
    "action": "accept",
    "reject_reason": null
  },
  "request_id": "req-confirm-001"
}

服务端确认

{
  "type": "tool_confirmation_processed",
  "tool_call_id": "call_abc123",
  "action": "accept",
  "request_id": "req-confirm-001"
}

错误场景

错误	原因	错误码
无效的 tool_call_id	ID 不存在于最后一条 AI 消息中	invalid_tool_call_id
非 pending 状态	工具调用已被处理或不在等待确认状态	invalid_tool_call_id
对话无 AI 消息	对话历史中没有 AI 的回复	invalid_tool_call_id
reason 未通过内容审核	accept/reject 附带的 reason 涉及违规内容。本次确认中止，工具调用保持 pending，修改 reason 后可重试	content_moderated
审核余额不足	内容审核需扣费但用户余额不足。本次确认中止，工具调用保持 pending	insufficient_balance

测试要点

测试建议

1. Accept 后需要 request_completion：Accept 本身不执行工具，客户端需发送 request_completion
2. Reject 后 AI 调整：拒绝后再请求补全，AI 应基于拒绝原因调整回复
3. 无效 tool_call_id：发送不存在的 ID 应收到错误消息
4. 重复确认：对已处理的工具调用再次发送确认应收到错误
5. accepting_edits 切换：开启自动接受后不应再出现 pending 状态
6. 混合工具调用：部分工具需确认、部分不需时的行为
7. awaiting_input 回复：用 role=tool 消息回复后应能继续补全
8. 超时行为：长时间不响应确认请求时的系统行为