Agent 工具程序搭建： 个内置工具让 Agent 学会写代码

前言

使用者痛点：上一次我们只实现了一个 get_wear mock 工具。功能极其单一，无法满足实际编码场景的需求。怎么说呢，

在本篇中。我们将把通用 Agent 升级为 Coding Agent让它能够：

• 读取文件、修改文件、输入命令、启动后台进程。怎么说呢，
• 统一工具定义方式。实现 schema 与实现代码合二为一，并保持类型安全。
• 同一套工具兼容 OpenAI 与 Anthropic 两大协议。
• 单个工具异常不导致整个 Agent 失效。
• 支持长时间运行的常驻命令。

每个 Feature 均提供独立可运行的 Demo。链接放在对应章节末尾，读者可直接体验。

Part ：defineTool + Zod · 工具定义的统一形态

使用者痛点：

1. Schema 与实现分离：新增或删除工具时需在两处代码修改，易出错。
2. 缺乏类型约束： 让 typo 难以捕获。
3. 硬编码 OpenAI 协议：

我们通过 defineTool 工厂一次性解决上述三大问题：

import { z } from "zod";interface ToolContext {
signal?: AbortSignal;}
interface FunctionTool

{
至于name，string;description: string;parameters: P;说起来，invoke: => Promise;}
function defineTool

(opts的观点是。{
至于name，string;description: string;parameters: P;invoke: => Promise;}): FunctionTool
{
return opts;}

关键点：

• Zod 用于声明 schema。Zod.infer 自动推导函数参数类型，实现“schema 改动即类型同步”。
• ctx 参数预留了 abort 信号还有后续可能的运行时上下文，不污染输入 schema。

再看示例，天气查询工具

const getWearTool = defineTool({
name这方面，"get_wear"。description: "查询某个城市的天气",parameters: z.object({
再看city，z.string.describe,}),invoke: async => {
await new Promise => setTimeout);if throw signal.reason;return `${city} 今天 °C 晴`;},})，

Zod → JSON Schema 的跨协议适配

L​LM 网站要求的是 JSON Schema。按理说，使用 Zod 内置的 .toJSONSchema 就可以完成转换。无需手动维护两套描述，

const resp = await this.client.chat.completions.create({
说到model，"deepseek-chat",messages: this.messages。tools: tools.map => ({
至于type，"function" as const,function: {
name这方面，t.name,description: t.description,parameters: z.toJSONSchema as Record,},})),});

If using Anthropic Provider,same .toJSONSchema result is placed into input_schema field—no extra changes required.

调用前的安全解析

const tool = tools.find => t.name === call.function.name);const input = tool.parameters.parse);const result = await tool.invoke;

User Pain Point: LLM 有时会返回缺失字段或错误类型的数据。通过 Zod 的 .parse。可以立即捕获异常并在后续错误隔离机制中处理，避免脏数据进入业务逻辑。

Part ：第一个 builtin 工具 · read_file

User Pain Point: 仅有单一工具无法完成真实开发任务—— 需要能读取源码文件。

import { readFile } from "node:fs/promises";const readFileTool = defineTool({
name的观点是。"read_file",description:
"读取指定方法的文这篇文章件。其实，文件超过 MAX_FILE_CHARS 时会自动截断",parameters: z.object({
从path来看。z.string.describe,}),invoke: async => {
const content = await readFile;if return "";if {
const headChars = Math.floor;const tailChars = Math.floor;const head = content.slice;
老实说，const tail = content.slice;const omitted = content.length - headChars - tailChars;return `${head}
${tail}`;}
return content;},})，

长文件截断策略防止上下文爆炸

• Description 中提前告知 LLM 截断行为：L​LM 会自行决定是否使用分页参数。
• 标记显式提醒：L​LM 能快速判断内容被裁剪，从而避免误判。

Part ：write_file / str_replace / bash + 错误隔离

User Pain Points:

• Coding Agent 必须拥有写入和局部替换能力。否则只能全盘覆盖，这既浪费 token 又容易引入错误。
• Coding Agent 调用外部命令时需要防止单个命令卡死整个循环。
• Coding Agent 必须对单个工具异常进行隔离，否则一次小错误会导致整条对话终止。

write_file：暴力覆盖

import { writeFile } from "node:fs/promises";const writeFileTool = defineTool({
再看name。"write_file",description:
"覆盖写入文件。仅在新建或全量重写时使用。",parameters: z.object({
说到path，z.string.describe。content: z.string.describe,}),invoke: async => {
await writeFile;return `wrote ${content.length} chars to ${path}`;},})，

str_replace：细粒度局部编辑

const strReplaceTool = defineTool({
至于name。"str_replace",description:
"在文件里把 old_str 替换成 new_str。默认只换第一处出现，传 replace_all=true 才会全部替换。",parameters:z.object({
path这方面，z.string.describe,old_str:z.string.describe,new_str:z.string.describe。replace_all:z.boolean.optional.describe,}),invoke:auto async=>{
let content=await readFile;if) throw new Error;content=replace_all?content.replaceAll:content.replace;await writeFile;return"OK"，},});

The default “first‑only” behavior matches most small‑scale edits a developer would ask an LLM to perform . For bulk refactoring LLM can explicitly set {replace_all:true}.

说到bash，同步执行短命令

import{exec}from"node:/child_process";import{promisify}from"noderutil";constexecAsync=promisify;constbashTool=defineTool.describe })。invoke :async=>{ const{stdout,stderr}=awaitexecAsync;constout= +，returnout.trim||"";},})，

• timeout :10_000 防止 LLM 调用卡死命令导致整个 loop 卡住。
• signal透传 abort 时向子进程发送 SIGTERM，实现真正的中止。

This design works for short‑lived commands but not for long‑running processes such as dev servers.

说到错误隔离，单工具异常不终结整体运行

consttoolMsgs=awaitPromise.all=>{letresult:string;try{consttool=tools.find;ifthrownewError;constinput=tool.parameters.parse);const r=awaittool.invoke;result=typeof r==='string '，r :JSON.stringify;}catch{result=Error:${err instanceof Error?err.message :String};}return{role:"tool & quotasConst。toolcallid :call.id,content :result};}))，话说回来，

• Try/Catch 包装每次调用 将异常包装为文字返回。让 LLM 决定后续动作。怎么说呢，
• 保持循环不中断 即使某个 tool 报错。也不会抛到外层导致整条对话结束。