为什么需要自定义 Tool？

先问个问题：LangChain 内置的那些搜索、计算器工具，真的够用吗？在真实业务里，答案往往是不够。AI 需要调用的，应该是那些真正属于你业务场景的“专属能力”。

举个例子，几条常见的需求场景就能说明问题：

场景	内置工具	自定义工具
前端开发	无	代码格式化、组件生成、样式转换
数据分析	简单计算	读取本地 CSV、生成图表配置
项目管理	无	创建 Jira 任务、发送钉钉通知
内容创作	无	文章排版、SEO 检查、配图生成

看到了吧，真正的价值往往藏在那些“内置工具没有”的地方。而 Tool 组件，正是把这种能力交到 AI 手里的桥梁。

它的核心价值其实很清晰：标准化接口，让 AI 完全不用关心内部怎么实现的；可复用性，封装一次到处能用；业务解耦，工具独立于对话流程，测试和维护都变得简单；还有能力扩展——让 AI 直接操作文件、数据库、外部 API，这才是 Agent 的灵魂。

Tool 核心原理与设计规范

Tool 的本质是什么？

说穿了，Tool 就是一个被“标准化包装”的函数。但它跟普通函数最大的区别在于，它需要满足三个条件，才能让 AI 理解并自主调用：

1. 有明确的名称
   ——AI 通过名字来选择要调用的工具。

2. 有清晰的描述
   ——AI 根据描述判断什么时候该调用它。

3. 有规范的参数定义
   ——AI 从用户输入中提取出参数。

对比一下就明白了：

// 普通函数 —— AI 无法直接调用
function formatCode(code: string, indent: number) {
  return code.trim();
}

// Tool —— 可以被 AI 调用
const codeFormatter = tool(
  async ({ code, indentSize }) => formatCode(code, indentSize),
  {
    name: "code_formatter",
    description: "格式化前端代码，支持 JS/TS/Vue",
    schema: z.object({
      code: z.string().describe("需要格式化的代码"),
      indentSize: z.number().default(2).describe("缩进空格数"),
    }),
  }
);

Tool 封装规范

几个关键的规范项，最好记一下：

规范项	要求	示例
名称命名	小写+下划线，动词开头	get_user_info、format_date
描述完整性	说明功能、适用场景、触发条件	"当用户需要...时使用此工具"
参数类型	使用 Zod 严格定义，避免 any	z.object({ id: z.string() })
参数描述	每个参数都要有 .describe()	z.string().describe("用户ID")
返回值规范	统一返回字符串，复杂数据用 JSON	JSON.stringify(data)
错误处理	try-catch 包裹，返回友好错误信息	return "错误：xxx"

Tool 与普通函数的区别

这张对比表可以帮你快速理解两者的根本差异：

维度	普通函数	Tool
调用者	开发者直接调用	AI 自主决定调用
输入	任意参数格式	必须符合 Zod Schema
输出	任意类型	建议返回字符串
文档	注释（可选）	必须有 name + description
错误处理	抛出异常	捕获异常，返回错误信息
可发现性	无	AI 可通过描述理解用途

前端 TS 封装自定义 Tool 完整步骤

基础 Tool 模板

直接上代码，这是最通用的模板：

import { tool } from "@langchain/core/tools";
import { z } from "zod";

// 步骤1：定义参数 Schema
const MyToolSchema = z.object({
  param1: z.string().describe("参数1的说明"),
  param2: z.number().optional().describe("参数2的说明（可选）"),
});

// 步骤2：定义工具函数
const myTool = tool(
  async (args: z.infer) => {
    try {
      // 步骤3：实现业务逻辑
      const { param1, param2 } = args;
      const result = await doSomething(param1, param2);
      // 步骤4：返回结果（字符串格式）
      return typeof result === "string" ? result : JSON.stringify(result);
    } catch (error) {
      // 步骤5：异常处理
      return `工具执行失败：${error instanceof Error ? error.message : String(error)}`;
    }
  },
  {
    name: "my_tool_name", // 工具唯一标识
    description: "工具功能描述，说明何时使用", // AI 理解依据
    schema: MyToolSchema, // 参数定义
  }
);

Tool 开发检查清单

开发完成后，不妨对照这个清单自查一遍：

• 工具名称是否清晰表达了功能？
• 描述是否说明了触发条件？
• 参数 Schema 是否完整定义了类型和说明？
• 异常是否被正确捕获并返回友好信息？
• 返回值是否是字符串类型？
• 是否考虑了空值和边界情况？

多场景实用 Tool 实战案例

案例一：前端代码格式化工具

// code-formatter.ts
import { tool } from "@langchain/core/tools";
import { z } from "zod";

// 模拟代码格式化（实际项目可集成 prettier）
function formatJa vaScript(code: string, indentSize: number = 2): string {
  const indent = " ".repeat(indentSize);
  // 简化的格式化逻辑（实际应使用 prettier.format）
  return code
    .split("n")
    .map(line => line.trim())
    .map(line => {
      if (line.startsWith("}") || line.startsWith("]") || line.startsWith(")")) {
        return line;
      }
      return indent + line;
    })
    .join("n");
}

export const codeFormatter = tool(
  async ({ code, language, indentSize }) => {
    try {
      if (!code || code.trim().length === 0) {
        return "错误：代码内容不能为空";
      }
      let formattedCode = code;

      switch (language) {
        case "ja vascript":
        case "typescript":
          formattedCode = formatJa vaScript(code, indentSize);
          break;
        case "json":
          formattedCode = JSON.stringify(JSON.parse(code), null, indentSize);
          break;
        default:
          return `暂不支持的语言: ${language}，当前支持：ja vascript, typescript, json`;
      }

      return formattedCode;
    } catch (error) {
      if (error instanceof SyntaxError) {
        return `代码语法错误：${error.message}`;
      }
      return `格式化失败：${error instanceof Error ? error.message : String(error)}`;
    }
  },
  {
    name: "code_formatter",
    description: `格式化前端代码，使代码更美观易读。使用场景：用户提供未格式化的代码、粘贴的代码排版混乱、需要统一代码风格时。支持的语言：ja vascript, typescript, json`,
    schema: z.object({
      code: z.string().describe("需要格式化的原始代码"),
      language: z
        .enum(["ja vascript", "typescript", "json"])
        .describe("代码语言类型"),
      indentSize: z
        .number()
        .min(2)
        .max(8)
        .default(2)
        .describe("缩进空格数，默认2"),
    }),
  }
);

案例二：本地文件读取工具

// file-reader.ts
import { tool } from "@langchain/core/tools";
import { z } from "zod";
import fs from "fs/promises";
import path from "path";

export const fileReader = tool(
  async ({ filePath, encoding = "utf-8" }) => {
    try {
      // 安全检查：防止路径遍历攻击
      const resolvedPath = path.resolve(filePath);
      if (!resolvedPath.startsWith(process.cwd())) {
        return `错误：无法访问项目目录外的文件：${filePath}`;
      }

      // 检查文件是否存在
      const stats = await fs.stat(resolvedPath).catch(() => null);
      if (!stats) {
        return `错误：文件不存在：${filePath}`;
      }

      // 限制文件大小（最大 1MB）
      if (stats.size > 1024 * 1024) {
        return `错误：文件过大（${(stats.size / 1024).toFixed(2)} KB），超过 1MB 限制`;
      }

      // 读取文件
      const content = await fs.readFile(resolvedPath, encoding as BufferEncoding);

      // 截断过长的内容
      const maxLength = 10000;
      if (content.length > maxLength) {
        return content.slice(0, maxLength) + `nn... 内容已截断（总长度 ${content.length} 字符）`;
      }

      return content;
    } catch (error) {
      return `读取文件失败：${error instanceof Error ? error.message : String(error)}`;
    }
  },
  {
    name: "file_reader",
    description: `读取本地文件内容。当用户需要查看文件内容、分析代码文件时使用。支持的文件类型：.txt, .js, .ts, .json, .md, .vue, .css, .html安全限制：只能读取项目目录内的文件，单文件最大 1MB`,
    schema: z.object({
      filePath: z.string().describe("文件路径，支持相对路径（如 ./src/index.ts）或绝对路径"),
      encoding: z
        .enum(["utf-8", "ascii"])
        .default("utf-8")
        .describe("文件编码，默认 utf-8"),
    }),
  }
);

案例三：网页内容抓取工具

// web-fetcher.ts
import { tool } from "@langchain/core/tools";
import { z } from "zod";

// 模拟网页抓取（实际项目可使用 axios + cheerio）
async function fetchWebContent(url: string): Promise {
  // 模拟请求延迟
  await new Promise(resolve => setTimeout(resolve, 500));
  // 模拟返回内容
  return `
欢迎访问示例网站
这是一个模拟的网页内容，实际项目中应该使用 axios/fetch 请求真实 URL。
主要内容包括：前端开发教程、AI 应用案例、LangChain 学习笔记等。
`;
}

// 简单的 HTML 文本提取
function extractText(html: string): string {
  return html
    .replace(/<script[^>]*>[sS]*?<\/script>/gi, "")
    .replace(/]*>[sS]*?<\/style>/gi, "")
    .replace(/<[^>]+>/g, " ")
    .replace(/s+/g, " ")
    .trim();
}

export const webFetcher = tool(
  async ({ url, extractMainContent = true }) => {
    try {
      // URL 格式验证
      try {
        new URL(url);
      } catch {
        return `错误：无效的 URL 格式：${url}`;
      }

      // 限制域名范围（可选，防止访问危险网站）
      const allowedDomains = process.env.ALLOWED_DOMAINS?.split(",") || [];
      const urlObj = new URL(url);
      if (allowedDomains.length > 0 && !allowedDomains.includes(urlObj.hostname)) {
        return `错误：不允许访问域名 ${urlObj.hostname}，仅支持：${allowedDomains.join(", ")}`;
      }

      // 抓取网页内容
      const html = await fetchWebContent(url);
      // 提取纯文本
      let content = extractMainContent ? extractText(html) : html;

      // 截断过长内容
      const maxLength = 5000;
      if (content.length > maxLength) {
        content = content.slice(0, maxLength) + `nn... 内容已截断`;
      }

      return content;
    } catch (error) {
      return `抓取网页失败：${error instanceof Error ? error.message : String(error)}`;
    }
  },
  {
    name: "web_fetcher",
    description: `抓取网页内容并提取主要文本。当用户需要了解某个网页的内容、获取在线文档信息时使用。注意：这是一个模拟实现，生产环境需要配置实际请求能力。`,
    schema: z.object({
      url: z.string().describe("需要抓取的网页 URL，格式如 https://example.com"),
      extractMainContent: z
        .boolean()
        .default(true)
        .describe("是否提取主要文本内容（去除HTML标签），默认 true"),
    }),
  }
);

案例四：数据转换工具（CSV/JSON 互转）

// data-converter.ts
import { tool } from "@langchain/core/tools";
import { z } from "zod";

export const dataConverter = tool(
  async ({ input, fromFormat, toFormat }) => {
    try {
      let result: string;

      // JSON 转 CSV
      if (fromFormat === "json" && toFormat === "csv") {
        const data = JSON.parse(input);
        if (!Array.isArray(data) || data.length === 0) {
          return "错误：JSON 必须是非空数组";
        }
        const headers = Object.keys(data[0]);
        const rows = data.map(obj =>
          headers
            .map(header => {
              let value = obj[header];
              if (value === undefined) return "";
              if (typeof value === "object") return JSON.stringify(value);
              return String(value).includes(",") ? `"${value}"` : value;
            })
            .join(",")
        );
        result = [headers.join(","), ...rows].join("n");
      }
      // CSV 转 JSON
      else if (fromFormat === "csv" && toFormat === "json") {
        const lines = input.trim().split("n");
        const headers = lines[0].split(",").map(h => h.trim());
        const records = lines.slice(1).map(line => {
          const values = line.split(",").map(v => v.trim().replace(/^"|"$/g, ""));
          return headers.reduce((obj, header, idx) => {
            obj[header] = values[idx] || "";
            return obj;
          }, {} as Record);
        });
        result = JSON.stringify(records, null, 2);
      } else {
        return `错误：不支持的转换类型 ${fromFormat} -> ${toFormat}，支持：json->csv 或 csv->json`;
      }

      return result;
    } catch (error) {
      if (error instanceof SyntaxError) {
        return `错误：JSON 格式解析失败 - ${error.message}`;
      }
      return `转换失败：${error instanceof Error ? error.message : String(error)}`;
    }
  },
  {
    name: "data_converter",
    description: `数据格式转换工具，支持 JSON 和 CSV 之间的互相转换。使用场景：用户需要将 JSON 数据导出为表格格式，或将 CSV 数据转换为可读的 JSON 结构。`,
    schema: z.object({
      input: z.string().describe("需要转换的原始数据内容"),
      fromFormat: z.enum(["json", "csv"]).describe("源数据格式"),
      toFormat: z.enum(["json", "csv"]).describe("目标数据格式"),
    }),
  }
);

Tool 调用异常处理方案

完整的异常处理框架

做好了工具，还得考虑健壮性。超时、网络异常、数据格式错误，这些都要有一套兜底逻辑。

// robust-tool.ts
import { tool } from "@langchain/core/tools";
import { z } from "zod";

// 带超时的 Promise 包装器
function withTimeout(promise: Promise, timeoutMs: number): Promise {
  return Promise.race([
    promise,
    new Promise((_, reject) =>
      setTimeout(() => reject(new Error(`操作超时（${timeoutMs}ms）`)), timeoutMs)
    ),
  ]);
}

// 定义返回类型（包含执行状态）
interface ToolResult {
  success: boolean;
  data?: any;
  error?: string;
  executionTime?: number;
}

// 示例：带完整异常处理的工具
export const robustTool = tool(
  async (args: any) => {
    const startTime = Date.now();
    try {
      // 1. 参数校验（Zod 已做，此处可补充业务校验）
      // 2. 执行核心逻辑（带超时）
      const result = await withTimeout(doBusinessLogic(args), 30000);
      // 3. 返回成功结果
      const toolResult: ToolResult = {
        success: true,
        data: result,
        executionTime: Date.now() - startTime,
      };
      return JSON.stringify(toolResult);
    } catch (error) {
      // 4. 分类错误处理
      let errorMessage: string;
      if (error instanceof Error) {
        if (error.message.includes("超时")) {
          errorMessage = `工具执行超时：${error.message}`;
        } else if (error.message.includes("ECONNREFUSED")) {
          errorMessage = "网络连接失败，请检查网络后重试";
        } else {
          errorMessage = `执行失败：${error.message}`;
        }
      } else {
        errorMessage = `未知错误：${String(error)}`;
      }
      const toolResult: ToolResult = {
        success: false,
        error: errorMessage,
        executionTime: Date.now() - startTime,
      };
      return JSON.stringify(toolResult);
    }
  },
  {
    name: "robust_tool",
    description: "带完整异常处理的工具示例",
    schema: z.object({}),
  }
);

async function doBusinessLogic(args: any): Promise {
  // 模拟业务逻辑
  return { status: "ok", data: "处理完成" };
}

异常类型与处理策略

异常类型	常见原因	处理策略	返回信息
参数校验错误	缺少必填参数、类型错误	Zod 自动校验 + 友好提示	"参数错误：xxx 是必填字段"
网络超时	请求耗时过长	设置超时、重试机制	"请求超时，请稍后重试"
资源不存在	文件/API 找不到	检查路径、提供建议	"文件不存在：xxx，请检查路径"
权限不足	无权访问资源	返回明确错误	"权限不足，无法访问 xxx"
数据格式错误	JSON 解析失败	提示正确格式	"JSON 格式错误，请检查：xxx"
限流/配额	调用次数过多	返回限流信息	"调用频率过高，请稍后再试"

工具集封装思路

工具分类管理

工具多了之后，管理起来就会变得有点头疼。一个比较优雅的做法是按功能分组管理。

// tools/index.ts
import { codeFormatter } from "./code-formatter";
import { fileReader } from "./file-reader";
import { webFetcher } from "./web-fetcher";
import { dataConverter } from "./data-converter";

// 按功能分类
export const devTools = {
  codeFormatter,
  // gitHelper, // Git 操作工具
  // npmSearch, // NPM 包搜索
};

export const dataTools = {
  dataConverter,
  // csvParser,
  // jsonValidator,
};

export const networkTools = {
  webFetcher,
  // httpRequest,
  // apiCaller,
};

export const fileTools = {
  fileReader,
  // fileWriter,
  // directoryLister,
};

// 统一获取所有工具
export function getAllTools() {
  return [
    ...Object.values(devTools),
    ...Object.values(dataTools),
    ...Object.values(networkTools),
    ...Object.values(fileTools),
  ];
}

// 按场景获取工具
export function getToolsForScenario(
  scenario: "frontend-dev" | "data-processing" | "web-scraping"
) {
  switch (scenario) {
    case "frontend-dev":
      return Object.values(devTools);
    case "data-processing":
      return Object.values(dataTools);
    case "web-scraping":
      return Object.values(networkTools);
    default:
      return getAllTools();
  }
}

动态工具注册

如果项目规模继续扩大，可以考虑引入一个工具管理器，支持运行时动态注册和查找。

// tools/registry.ts
interface ToolRegistry {
  [key: string]: ReturnType;
}

class ToolManager {
  private tools: ToolRegistry = {};

  // 注册工具
  register(tool: ReturnType): void {
    const name = tool.name;
    if (this.tools[name]) {
      console.warn(`工具 ${name} 已存在，将被覆盖`);
    }
    this.tools[name] = tool;
  }

  // 批量注册
  registerAll(tools: ReturnType[]): void {
    tools.forEach(t => this.register(t));
  }

  // 获取单个工具
  get(name: string): ReturnType | undefined {
    return this.tools[name];
  }

  // 获取所有工具
  getAll(): ReturnType[] {
    return Object.values(this.tools);
  }

  // 按名称模式匹配
  search(pattern: RegExp): ReturnType[] {
    return Object.entries(this.tools)
      .filter(([name]) => pattern.test(name))
      .map(([, tool]) => tool);
  }
}

export const toolManager = new ToolManager();

可扩展的工具基类

如果是团队协作，定义一套基类规范会很有帮助。

// tools/base-tool.ts
import { tool } from "@langchain/core/tools";
import { z, ZodObject } from "zod";

// 工具配置接口
interface ToolConfig {
  name: string;
  description: string;
  schema: ZodObject;
  timeout?: number;
  retries?: number;
}

// 抽象工具类
export abstract class BaseTool {
  protected config: ToolConfig;

  constructor(config: ToolConfig) {
    this.config = config;
  }

  // 子类需要实现的核心逻辑
  protected abstract execute(args: any): Promise;

  // 前置钩子
  protected beforeExecute(args: any): void {
    console.log(`[Tool] 开始执行 ${this.config.name}，参数：`, args);
  }

  // 后置钩子
  protected afterExecute(result: string): void {
    console.log(`[Tool] 执行完成 ${this.config.name}，结果长度：${result.length}`);
  }

  // 错误处理钩子
  protected onError(error: Error, args: any): string {
    return `${this.config.name} 执行失败：${error.message}`;
  }

  // 构建 LangChain Tool
  build() {
    const self = this;
    return tool(
      async (args: any) => {
        self.beforeExecute(args);
        try {
          const result = await self.execute(args);
          self.afterExecute(result);
          return result;
        } catch (error) {
          return self.onError(error as Error, args);
        }
      },
      {
        name: this.config.name,
        description: this.config.description,
        schema: this.config.schema,
      }
    );
  }
}

// 使用示例
class CalculatorTool extends BaseTool {
  constructor() {
    super({
      name: "calculator",
      description: "数学计算工具",
      schema: z.object({
        expression: z.string(),
      }),
    });
  }

  protected async execute(args: { expression: string }): Promise {
    // 安全计算
    const result = Function('"use strict";return (' + args.expression + ")")();
    return result.toString();
  }
}

// 注册使用
const calculator = new CalculatorTool().build();

完整实战 - 智能代码助手

最后，把前面这些工具组合起来，做一个能读文件、格式化代码、转换数据格式的智能代码助手。完整的 LangGraph 工作流如下：

import { ChatOpenAI } from "@langchain/openai";
import { StateGraph, MessagesAnnotation, START, END } from "@langchain/langgraph";
import { HumanMessage, ToolMessage } from "@langchain/core/messages";
import dotenv from "dotenv";
import { codeFormatter } from "./code-formatter.ts";
import { fileReader } from "./file-reader.ts";
import { dataConverter } from "./data-converter.ts";

dotenv.config();

async function smartCodeAssistant() {
  // 1. 初始化模型
  const model = new ChatOpenAI({
    apiKey: process.env.DASHSCOPE_API_KEY,
    configuration: {
      baseURL: process.env.DASHSCOPE_API_URL,
    },
    model: "qwen-plus",
    temperature: 0.3,
  });

  // 工具列表
  const tools = [codeFormatter, fileReader, dataConverter];
  const modelWithTools = model.bindTools(tools);

  // -----------------------
  // 节点1：AI 思考是否调用工具
  // -----------------------
  async function callModel(state: typeof MessagesAnnotation.State) {
    const response = await modelWithTools.invoke(state.messages);
    return { messages: [response] };
  }

  // -----------------------
  // 节点2：执行工具（核心修复）
  // -----------------------
  async function executeTools(state: typeof MessagesAnnotation.State) {
    const lastMessage = state.messages[state.messages.length - 1];

    // 如果没有工具调用，直接返回
    if (!("tool_calls" in lastMessage) || !lastMessage.tool_calls) {
      return { messages: [] };
    }

    // 执行所有工具调用
    const toolResults = [];
    for (const toolCall of lastMessage.tool_calls) {
      console.log(`n? 正在执行工具：${toolCall.name}`);
      console.log(`? 参数：${JSON.stringify(toolCall.args)}`);

      // 找到对应的工具
      const tool = tools.find((t) => t.name === toolCall.name);
      let result;
      if (tool) {
        try {
          result = await tool.invoke(toolCall.args);
        } catch (e) {
          result = `工具执行失败：${e}`;
        }
      } else {
        result = "未知工具";
      }
      console.log(`✅ 工具返回：${result}`);

      toolResults.push(
        new ToolMessage({
          content: result,
          tool_call_id: toolCall.id,
        })
      );
    }
    return { messages: toolResults };
  }

  // -----------------------
  // 构建工作流（支持自动工具调用）
  // -----------------------
  const workflow = new StateGraph(MessagesAnnotation)
    .addNode("model", callModel)
    .addNode("executeTools", executeTools) // 添加工具执行节点
    .addEdge(START, "model")
    .addEdge("model", "executeTools") // AI → 执行工具
    .addEdge("executeTools", "model") // 执行完 → 让AI总结结果
    .addEdge("executeTools", END); // 结束

  const app = workflow.compile();

  // =======================
  // 用户提问
  // =======================
  const userRequest = `请帮我做以下事情：1. 读取当前目录下的 package.json 文件2. 提取其中的依赖信息3. 将依赖信息转换为表格格式`;

  console.log(`? 用户: ${userRequest}n`);
  console.log("? 执行中...n");

  // 运行
  const result = await app.invoke({
    messages: [new HumanMessage(userRequest)],
  });

  // 输出最终回答
  const finalAnswer = result.messages.at(-1);
  console.log("n? 最终回答：n", finalAnswer?.content);
}

smartCodeAssistant();

结语

通过这篇教程，我们深入学习了 LangChain 中自定义 Tool 的完整开发流程。Tool 是让 AI 具备"动手能力"的关键，掌握它就能将 AI 与你的业务系统深度集成。希望这些内容对你有实实在在的帮助。