在上一篇中我们把 Agent 变成了一个聊天接口，能记住对话历史并把事件转发给上层。其实，但现实中使用者常遇到的痛点是：当模型返回工具调用时Agent 并不会真正执行工具。也不会把结果回馈给模型，从而导致对话卡在“未完成”的状态。为了解决这个痛点，需要实现完整的工具调用闭环。

痛点一这方面，模型返回 tool_call 却没有被执行

模型只能返回一个结构化的调用意图：

{ type: "tool_call"。id: "call-123",name: "echo",arguments: { value: "hello" } }

但这只是意图，真正的执行必须由本地 Agent 完成。若 Agent 不做处理。使用者会看到“无法读取文件”或“命令执行失败”等错误，却不知道为何。

方法

• Agent 必须在收到 tool_call 后查找对应本地工具并执行。
• 将执行结果包装为 ToolResultMessage 并追加到消息历史。
• 请求模型，让其看到工具结果后给出最终答案。

至于痛点二。一次 prompt 可能包含多轮交互

传统纯文本 Agent 的一次 prompt 对应一次模型请求，但加入工具后一次 prompt 可能产生多次 “turn”。话说回来，

关键流程

User 提问
-> 模型决定调用工具
-> Agent 执行
-> 将结果追加到历史
->
请求模型
-> 给出最终回答

ToolDefinition 与 AgentTool 的区别

ToolDefinition

{ name: string;description: string;parameters: Schema;}

AgentTool

{ name,description,parameters。execute: Promise }

User 在使用时只需要传入可用的 AgentTool;其实，AgentLoop 会从中提取三字段传递给 Provider。

AgentContext 与事件类型

Add tools to context:

{ systemPrompt?,messages,tools?话说回来，: readonly AgentTool }

Add events for tool execution:

{ type:"tool_execution_start" | "tool_execution_end" | ... }

将工具注入 Agent 并保持稳定列表

• Aggreate tools snapshot in constructor.
• Create a fresh context copy on each prompt.
• This guarantees that concurrent prompts see same tool set.

constructor { this.tools =;}

仅将 ToolDefinition 交给 Provider

 );}

const response = config.provider.stream( config.model。{ systemPrompt: context.systemPrompt,messages,tools: toolDefinitions,},{ signal } );

统一 ToolResultMessage 构造与错误包装

• Create helper to generate result message.
• Error handling uses safe string conversion via errorMessage.

executeToolCall 实现细节拆解

说到关键点回顾，

• 先发起 start/stop events：
• 按名称查找工具且不使用非空断言：
• 参数校验前复制强类型值：
• 异常统一包装成 ToolResultMessage：
• 两次 abort 检查：

从 AssistantMessage 中提取所有 Tool Calls

为什么需要过滤？

• Assistant 回复可能混合文本、思考和多条工具调用；我们只关心后者，

示例这方面，

// message.content 示例：
// getToolCalls 返回包含 call-1 的对象。javascript
getToolCalls.id // => "call-1"
`
`
`
`
`
`
`
`
`
`

循环处理多条 Tool Call 的 while 循环结构
typescript
while{
const assistant = await streamAssistantResponse;messages.push;
const calls = getToolCalls;if {
// Final answer or error → finish loop.
break;按理说，}
const results=;for{
const res=await executeToolCall;messages.push;results.push;if break，怎么说呢，}
// 如果取消则安全结束。

}



场景一的观点是，最终回答

如果 stopReason!== 'tool_use',则直接结束循环，发送 agent_end.

再看场景二，需要进一步调用工具

按顺序逐个执行。并在每个 turn_end 时记录已完成的 tools.

至于场景三，取消

立即停止剩余工具，避免后续请求，并插入一个特殊 aborted Assistant 消息，使上层能正常收尾。


测试闭环成功

使用 Faux Provider 可预置两轮响应：


第一次返回 {"role":"assistant","content":}；

第二次返回最终文本 "done"。


创建最简单 echo 工具并验证：

ts
const echoParams = Type.Object});const echo:{...} satisfies AgentTool;

const agent=new Agent({
provider:faux.provider。model:faux.model,tools:,now=>Date.now
});话说回来，

const assistant=await agent.prompt;expect.toMatchObject({
stopReason:'stop',content:
});

从验证日志来看，


两条 Faux 响应均被消费；

工具结果已添加至消息历史；老实说，

最终 Assistant 消息正确。怎么说呢，



常见错误测试



场景
验证目标




未注册工具
输出 "Unknown tool \"missing\""


参数非法
返回错误信息且不触发 execute


工具内部抛错
包装成 isError:true 并显示 "failed"


执行期间取消
确认后续工具未启动。最终状态为 "aborted"





如何方便你上手？话说回来，


复制上述代码到自己的项目中；按理说，

定义自己的 Tools只需实现 execute。

运行测试确保闭环无误。


这样，你的 Coding Agent 就能做到「提出行动 → 本地执行 → 模型观察」完整循环。


小结

通过以下六步，你实现了真正的工具调用闭环：

1️⃣ 把 // 提供给 Provider。2️⃣ 从 Assistant 回复中提取所有  调用。3️⃣ 按名称定位本地实现并校验参数。4️⃣ 捕获异常、未知或非法参数统一包装成  消息。5️⃣ 将  添加到消息历史，请求模型。6️⃣ 当无新调用或被取消时安全结束。

现在你可以在此基础上继续
例如集成文件程序读写、shell 命令等实际副作用，并通过 CLI 或 Web UI 为使用者提供直观体验。

祝你编码愉快 🚀