[!info] related notes

• 所属 MOC: AI Agent Application MOC
• 相关: Event Type, Tool Call UI

Tool Call Start

一句话定义

Tool Call Start 是 Agent 开始调用工具时发出的事件。前端收到后显示”正在搜索…”等工具调用状态卡片。

核心原理

数据格式

{
  "event": "tool_call_start",
  "data": {
    "tool_call_id": "tc_001",
    "tool_name": "search_knowledge",
    "arguments": {"query": "膝关节康复"}
  }
}

前端处理

function handleToolCallStart(data: ToolCallStartData) {
  setMessages(prev => {
    const last = prev[prev.length - 1];
    return [
      ...prev.slice(0, -1),
      {
        ...last,
        toolCalls: [
          ...(last.toolCalls || []),
          {
            id: data.tool_call_id,
            name: data.tool_name,
            arguments: data.arguments,
            status: 'running',
          }
        ]
      }
    ];
  });
}

事件序列

tool_call_start → tool_call_result
     │                  │
     ▼                  ▼
  显示"执行中..."    更新为"完成"

常见坑

1. 不显示状态: 收到事件但 UI 没有更新
2. 参数太大: arguments 包含大量数据，事件太大
3. 不跟踪 tool_call_id: 无法关联后续的 result 事件

参考资料

• Event Type
• Tool Call UI