为什么自定义 Tool 是必须的？

问一个问题：LangChain 内置的搜索、计算器等工具，真的能满足实际业务需求吗？答案通常是否定的。AI 真正需要调用的，是那些贴合你业务场景的“专属能力”。

举例来说，以下几个常见场景即可说明问题：

可以看出，真正的价值往往隐藏在“内置工具所不具备”的领域。而 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 封装规范指南

以下关键规范项建议牢记：

Tool 与普通函数的根本区别

下表可助你快速理解两者的本质差异：

前端 TypeScript 封装自定义 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(/]*>[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: "处理完成" };
}

常见异常类型及处理策略

工具集的封装思路

按功能分类管理工具

当工具数量增多时，管理难度随之上升。一个较为优雅的解决方案是按功能进行分组管理。

// 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 与业务系统的深度集成。希望这些内容能为你带来切实帮助。