很多人在学 AI 编程与智能体开发时会遇到一个很典型的问题模型对话很流畅一到“让智能体真正做点事”就卡住了。比如让它查一下当前系统时间、算一笔账、读取一个本地文件它只会给你一段文字不会真的去执行。原因是很多初学者还没有意识到——大模型只是一个非常强的“文本推理大脑”它不会主动调用外部函数也不会访问你的本地环境。智能体之所以能“动起来”关键在工具Tool这一层。在厦门大学林子雨老师的《AI编程与智能体开发》课程中8.8.3 小节单独安排了一次“自定义工具实操”。这个章节放在整个课程的实操阶段目的很明确帮助学习者跨过智能体开发中最核心的一道坎把自己写好的普通函数变成模型可以理解并调用的工具再把它挂载到智能体里完成真实任务。本篇文章围绕这个课程节点展开内容分为三块第一讲清楚自定义工具的原理与设计方式第二给出从零到一的最小可运行示例第三展示接入真实大模型和主流框架时的实操代码、验证方法、常见问题与工程建议。读完这篇文章你会理解“会写函数”和“会写工具”之间的区别也能亲自动手扩展一个能查时间、能计算、能处理简单任务的智能体。1. 自定义工具解决的是智能体的“行为能力”问题先看一个最常见的场景。你在 Agent 开发平台里创建了一个智能体然后在对话框里输入“帮我计算一下 3.5 乘以 7.2 再除以 2 的结果。”模型很聪明它可能会直接给出计算过程甚至算出结果。但这里有一个关键问题这个结果是模型“猜”出来的还是真正经过计算程序算出来的如果是简单乘法模型大概率算得对但如果是复杂到几十个变量的公式、需要读取实时数据、需要调用内部接口的任务模型就无能为力了。这就是智能体开发中经常说的“模型会想但不会做”。它擅长的是语言理解与文本生成不擅长执行真实动作。而“自定义工具”要解决的恰恰是这个问题。引入工具之后整个流程会发生变化用户提出需求模型判断这个需求需要调用哪个工具模型按工具的规则生成参数程序真正执行工具函数执行结果返回给模型模型根据结果组织最终回答。在这个流程里模型扮演的是“决策者”的角色工具函数扮演的是“执行者”。前面负责理解意图、拆解任务、决定调用什么后面负责把结果真实计算出来。这就是为什么在 AI 编程与智能体开发课程中“自定义工具实操”会被单独拿出来讲。它不是一个可选项而是从“会对话的机器人”走向“能办事的智能体”的关键一步。这里也顺便纠正一个常见误区很多人以为工具就是把函数写出来然后叫它“工具”而已。实际上自定义工具必须包含两层结构一层是给模型看的“说明书”告诉模型这个工具是干什么的、有哪些参数另一层是给程序用的“执行逻辑”也就是真正运行的函数本体。缺了第一层模型不知道怎么调用缺了第二层调用了也无法真正执行。2. 工具与函数调用核心概念与工作机制要掌握自定义工具先要理解两个词Tool工具和 Function Calling函数调用。在大多数智能体开发框架和模型接口中这两者经常同时出现。Tool 是工具在模型层面的表达形式。它本质上是一个 JSON 结构里面包含工具名称、工具说明、参数定义等信息。模型拿到这个结构之后就会知道“我这里有哪些工具可以用每个工具该怎么传参数”。Function Calling 是模型的一种能力。启用函数调用之后模型在回答用户问题时不再只能输出纯文本而是可以输出一个“我想调用某个工具”的结构化结果。这个结果包含两条关键信息调用的工具名以及传给工具的参数。两者结合起来就构成了自定义工具的基本工作机制。我们看一个典型的工具定义。以 JSON Schema 形式描述一个查询天气的工具{ type: function, function: { name: get_weather, description: 查询指定城市的当前天气情况, parameters: { type: object, properties: { city: { type: string, description: 城市名称例如厦门、北京 } }, required: [city] } } }这个 JSON 结构就是给模型看的“说明书”。它的含义是系统里有一个工具叫get_weather它可以查询天气查询时你需要传入一个参数city参数类型是字符串。当用户问“厦门今天天气怎么样”时模型看到这个工具定义会返回一条类似下面的调用意图{ name: get_weather, arguments: {\city\: \厦门\} }注意模型到这里并没有真正查询天气。它只是告诉程序我决定使用get_weather这个工具传给它的参数是“厦门”。真正调用天气接口、获取结果、返回数据的工作仍然要由程序代码完成。为了帮助大家记忆可以把一个自定义工具拆成五个要素要素作用示例工具名称模型和程序共同识别的唯一标识get_weather工具描述告诉模型什么时候该用这个工具“查询指定城市的当前天气”参数定义指定模型需要填哪些参数、参数类型是什么city字符串必填执行函数真正运行的程序逻辑调用天气服务接口并返回结果返回结果回传给模型的文本或结构化数据还有一个容易混淆的概念工具、插件与 API 有什么区别简单理解API 是外部系统提供的接口工具是模型可以调用的函数封装插件则通常是包含多个工具的完整功能包。一个工具内部可以调用多个 API一个插件又可以把多个工具组合在一起。开发时不必纠结定义只要抓住“工具是模型与程序之间的桥梁”这个本质即可。3. 环境准备与开发框架选型在进入代码之前先准备好开发环境。下面推荐的组合可以覆盖课程实操和日常练习版本信息以实际安装为准本文不绑定过死的版本号重点演示通用思路。3.1 运行环境本机建议安装 Python 3.9 或更高版本。在命令行执行python --version可以确认版本。为了方便管理依赖建议为项目创建独立的虚拟环境mkdir custom-tool-lab cd custom-tool-lab python -m venv venv # Windows venv\Scripts\activate # macOS / Linux source venv/bin/activate3.2 选型建议当前开发自定义工具主要有三条路线直接使用大模型服务商的 SDK以原生 Function Calling 方式开发。这种方式最透明也最容易理解底层原理。使用 LangChain 等 Agent 开发框架通过tool装饰器快速定义工具。这种方式开发效率高适合工程化项目。使用 Coze、Dify 等低代码平台在界面中配置工具。这种方式门槛最低适合原型验证但与代码开发有点距离。从课程实操角度看建议先走第一条路线搞懂原理后再用框架。本文也会依次演示。3.3 API Key 管理接入真实大模型时通常需要设置 API Key。这里必须强调一个安全规范不要把 API Key 硬编码到代码中也不要提交到 Git 仓库。推荐使用环境变量或.env文件。可以先安装python-dotenv来读取配置pip install python-dotenv openai然后在项目根目录创建.env文件# 文件路径.env # 请将下方的 YOUR_API_KEY 替换为你自己的密钥 # 请将下方的 YOUR_MODEL_NAME 替换为你实际使用的模型名称 OPENAI_API_KEYYOUR_API_KEY OPENAI_MODEL_NAMEYOUR_MODEL_NAME之后在 Python 代码中加载# 文件路径config.py import os from dotenv import load_dotenv load_dotenv() API_KEY os.getenv(OPENAI_API_KEY) MODEL_NAME os.getenv(OPENAI_MODEL_NAME)如果你使用的是国内大模型服务接口通常也兼容 OpenAI 风格的调用方式只需要在创建客户端时修改base_url和model即可。具体地址和模型名称以你实际使用的服务商文档为准。4. 自定义工具实操从本地可运行的最小示例开始正式写代码之前先做一个不依赖大模型 API 的最小示例。这个示例的目的不是替代真实模型而是让你直观看到“模型决定调用工具 → 程序执行工具 → 结果返回”这个完整链路。4.1 定义两个基础工具函数我们定义两个非常简单的工具一个获取当前本地时间一个执行四则运算。演示时用普通 Python 函数即可。# 文件路径tools.py 工具函数实现部分。 真实项目中这里的每个函数都可以替换为读取数据库、 调用外部 API、操作文件等真实业务逻辑。 from datetime import datetime def get_current_local_time() - str: 返回当前本地时间格式为 YYYY-MM-DD HH:MM:SS return datetime.now().strftime(%Y-%m-%d %H:%M:%S) def calculate(expression: str) - str: 计算简单的四则运算表达式。 注意为了保证演示安全这里只允许输入数字和 - * / 符号。 生产环境中请使用专业计算库或自行实现解析器不要直接 eval 任意字符串。 allowed_chars set(0123456789-*/(). ) if not set(expression).issubset(allowed_chars): return 非法表达式只能包含数字、括号和四则运算符号 try: # 仅用于教学演示真实项目应避免直接 eval 用户输入 result eval(expression) return str(result) except Exception as e: return f表达式计算失败: {e}这里有两个细节值得注意。第一每个函数都写了清晰的文档字符串这份注释在后面会变成模型看到的工具描述。第二calculate对输入做了字符白名单校验避免随意执行用户传入的代码。这个习惯在自定义工具开发中非常重要。4.2 为模型准备工具定义有了函数实现还需要准备一份模型能读懂的“说明书”。# 文件路径tool_schema.py tools_schema [ { type: function, function: { name: get_current_local_time, description: 获取当前本地时间返回格式为 YYYY-MM-DD HH:MM:SS, parameters: { type: object, properties: {}, required: [] } } }, { type: function, function: { name: calculate, description: 计算四则运算表达式例如 3 5 * 2结果返回数字字符串, parameters: { type: object, properties: { expression: { type: string, description: 需要计算的数学表达式 } }, required: [expression] } } } ]可以看到没有参数的函数它的properties就是一个空对象有参数的函数需要把每个参数的类型和说明写清楚。required表示哪些参数是必填的。4.3 用模拟模型演示工具调用主流程在没有接入真实模型之前先写一个简单的规则函数模拟模型选择工具的过程。逻辑很简单用户输入包含“时间”就调用时间工具包含“计算”就调用计算工具。# 文件路径mock_agent.py import json from tools import get_current_local_time, calculate from tool_schema import tools_schema # 工具名到实际函数的映射表 TOOL_MAP { get_current_local_time: get_current_local_time, calculate: calculate, } def mock_llm_call(prompt: str): 模拟模型判断返回一个工具调用意图 if 时间 in prompt: return { name: get_current_local_time, arguments: {} } if 计算 in prompt: expression prompt.replace(计算, ).strip() return { name: calculate, arguments: {expression: expression} } return None def run_agent(prompt: str): print(f用户提问{prompt}) intent mock_llm_call(prompt) if intent is None: print(模型判断不需要调用工具) print(模型回答抱歉我暂时无法处理这个问题。) return tool_name intent[name] arguments intent[arguments] print(f模型选择工具{tool_name}) print(f工具参数{json.dumps(arguments, ensure_asciiFalse)}) # 执行工具 func TOOL_MAP[tool_name] result func(**arguments) print(f工具执行结果{result}) # 正常情况下这里的执行结果会再次传给模型由模型生成最终回答 final_answer f根据工具返回结果我的回答是{result} print(f模型最终回答{final_answer}) if __name__ __main__: run_agent(帮我计算 3 5 * 2) print() run_agent(现在几点了)在项目根目录执行python mock_agent.py预期输出大致如下用户提问帮我计算 3 5 * 2 模型选择工具calculate 工具参数{expression: 3 5 * 2} 工具执行结果13 模型最终回答根据工具返回结果我的回答是13 用户提问现在几点了 模型选择工具get_current_local_time 工具参数{} 工具执行结果2025-xx-xx xx:xx:xx 模型最终回答根据工具返回结果我的回答是2025-xx-xx xx:xx:xx这个小例子已经把自定义工具的完整链路走通了。你可能会说“这个模型选择逻辑太简单了根本不是真正的大模型。” 没错这个 mock 函数只是为了让你看清楚流程。真正的模型只是在“判断调用哪个工具、生成什么参数”这一步做了更聪明的决策后面的执行逻辑和回传逻辑完全一致。5. 接入真实大模型Function Calling 版完整代码理解了原理之后下面把 mock 部分替换成真实的大模型调用。这里使用 OpenAI 风格的 SDK 接口国内多数兼容接口也可以按同样方式接入。5.1 安装依赖与客户端初始化如果你还没有安装依赖先执行pip install openai python-dotenv然后在代码中初始化客户端。客户端默认读取环境变量中的 API Key如果你的服务商需要自定义地址可以显式传入base_url。# 文件路径real_agent.py import json import os from openai import OpenAI from dotenv import load_dotenv from tools import get_current_local_time, calculate from tool_schema import tools_schema load_dotenv() client OpenAI( api_keyos.getenv(OPENAI_API_KEY), # 如果使用的是兼容 OpenAI 接口的国内服务取消下面这行注释并填写服务商地址 # base_urlhttps://你的服务商地址/v1, ) MODEL_NAME os.getenv(OPENAI_MODEL_NAME, gpt-4o-mini) TOOL_MAP { get_current_local_time: get_current_local_time, calculate: calculate, }注意如果你使用的是国内模型模型名称必须改为你实际可用的模型 ID。这里不写死是为了适应不同读者的环境。5.2 执行工具并生成最终回答下面定义两个函数一个负责根据模型返回的工具名执行对应的 Python 函数另一个负责把工具结果回传给模型。# 继续编写 real_agent.py def execute_tool_call(tool_call): 根据模型返回的 tool_call 执行工具函数 tool_name tool_call.function.name arguments json.loads(tool_call.function.arguments) print(f模型选择工具{tool_name}) print(f工具参数{json.dumps(arguments, ensure_asciiFalse)}) func TOOL_MAP[tool_name] result func(**arguments) print(f工具执行结果{result}) return { role: tool, tool_call_id: tool_call.id, content: str(result), } def run_agent(prompt: str, max_steps: int 3): messages [{role: user, content: prompt}] print(f用户提问{prompt}) for step in range(max_steps): response client.chat.completions.create( modelMODEL_NAME, messagesmessages, toolstools_schema, ) message response.choices[0].message # 如果模型没有返回工具调用说明它可以基于已有内容回答 if not message.tool_calls: print(f模型最终回答{message.content}) return # 先把模型的决策追加到消息列表 messages.append(message) # 依次执行模型请求的所有工具调用 for tool_call in message.tool_calls: tool_result execute_tool_call(tool_call) messages.append(tool_result) print(已达到最大调用轮数停止继续调用。) if __name__ __main__: run_agent(帮我计算 3 5 * 2 的结果)这段代码有几个重要的设计点第一模型返回的tool_calls是一个列表说明一次回答可能请求调用多个工具。遍历执行并把每个结果都按role: tool的方式追加回消息列表模型才能继续工作。第二messages中必须包含之前的用户提问、模型决策和工具结果。整个对话上下文是连在一起的工具结果如果漏掉模型会无法判断下一步应该怎么回答。第三循环需要设置最大轮数。真实场景中模型可能反复调用工具甚至陷入循环设置max_steps可以避免程序无休止运行。执行前在.env中填好 API Key 和模型名称然后运行python real_agent.py如果一切正常你会看到模型先返回一个工具调用意图然后程序执行calculate函数随后模型基于计算结果给出最终答案。这个版本已经是一个真正的自定义工具小项目了。6. 使用 LangChain 简化自定义工具开发如果你在工程化项目中使用 LangChain定义工具可以更简洁。LangChain 提供了tool装饰器只需要写好函数和文档字符串框架会自动帮你生成 JSON Schema。6.1 用 tool 装饰器定义工具# 文件路径langchain_tools.py from datetime import datetime from langchain_core.tools import tool tool def get_current_local_time() - str: 返回当前的本地时间格式为 YYYY-MM-DD HH:MM:SS return datetime.now().strftime(%Y-%m-%d %H:%M:%S) tool def calculate(expression: str) - str: 计算四则运算表达式。 参数 expression: 需要计算的数学表达式。 例如3 5 * 2 allowed_chars set(0123456789-*/(). ) if not set(expression).issubset(allowed_chars): return 非法表达式 return str(eval(expression))注意函数名和文档字符串会直接影响模型的调用行为。文档字符串里的说明就是模型读到的工具描述写得不清楚模型就会在错误的时候调用错误工具。6.2 工具注册与挂载到 Agent在 LangChain 中创建 Agent 时把工具列表传进去即可。不同版本的 LangChain API 差异较大这里给出一个较常见的示意写法。具体以你当前安装版本的官方文档为准。# 文件路径langchain_agent_demo.py from langchain_tools import get_current_local_time, calculate # 注册工具列表 tools [get_current_local_time, calculate] print(tools) # 将 tools 传入 Agent 创建方法 # 不同版本 LangChain 的 Agent 创建方式不同这里不展开 # 常见做法 # agent create_agent(model, tools) # agent.invoke({messages: [(user, 帮我计算 3 5 * 2)]})为什么不在这里给出完整的 Agent 创建代码因为 LangChain 的create_agent、initialize_agent等方法在不同版本中的参数和类名差异较大写死某一个版本反而容易误导读者。你需要做的是理解两件事第一tool装饰器会自动把函数转成工具对象第二在 Agent 初始化时传入tools列表框架就会在模型推理时自动附加工具定义。7. 运行结果与验证方法不管使用原生 Function Calling 还是 LangChain运行后的验证逻辑都是一致的。下面给出一个标准的验证清单。7.1 启动命令本地最小示例python mock_agent.py真实模型接入python real_agent.pyLangChain 示例python langchain_agent_demo.py7.2 预期输出以real_agent.py为例正常输出应该包含四个阶段用户提问帮我计算 3 5 * 2 的结果 模型选择工具calculate 工具参数{expression: 3 5 * 2} 工具执行结果13 模型最终回答3 5 * 2 的计算结果是 13。这四个阶段缺一不可。特别要关注“工具执行结果”它必须由代码真实计算出来而不是模型直接“猜”出来的。7.3 判断标准如何确定你的自定义工具成功了可以从三个角度验证功能维度用户输入自然语言模型能自动选择正确工具并且参数传得准确。执行维度工具函数真实执行并返回结果返回值正确。反馈维度模型读取工具结果后能基于结果生成合理回答而不是忽略工具结果自说自话。如果第三个维度出现问题比如模型返回了None或重新说了一段不相干的内容优先检查messages列表中的tool_call_id是否对得上、工具结果是否按role: tool正确追加。失败时先不要急着怀疑框架。第一步看日志里模型是否输出了tool_calls第二步看参数是否被正确解析第三步看工具函数是否抛出异常第四步看最终回答是否基于工具结果。按照这个顺序排查大部分问题都能定位。8. 自定义工具常见问题与排查思路在实践过程中下面几个问题几乎每个人都会遇到。这里用表格整理成排查清单。问题现象可能原因排查方式解决方案模型一直不调用工具工具描述不清晰模型判断不出何时使用查看打印出的工具定义检查 description 是否具体改写描述明确触发场景和示例模型返回的 arguments 解析报错模型输出了非标准 JSON打印原始 arguments 字符串用 try-except 包裹 json.loads失败时提示模型重新生成参数工具函数执行结果报错参数类型不匹配或函数内部异常打印实际传入的参数确认类型在函数入口做参数类型校验和异常捕获模型忽略工具结果工具结果未按role: tool回传或tool_call_id不匹配打印 messages 列表检查消息结构修正消息组装逻辑API Key 未加载环境变量没有设置或 .env 文件未读取在代码中临时打印 os.getenv(OPENAI_API_KEY)确认 .env 文件路径和变量名工具调用陷入死循环模型不断返回工具调用且没有终止条件查看日志确认工具调用轮数设置 max_steps 最大轮数超过后强制退出使用框架时提示 tools 格式错误LangChain 版本之间 API 不兼容查看框架当前版本文档按官方文档调整创建 Agent 的方式在这些问题中最容易被忽略的是“工具描述”的质量。很多初学者把工具描述写得很随意例如“计算用的工具”模型自然不知道什么时候该调用。更好的写法是明确场景比如“当用户需要计算数学表达式时使用例如 3 加 5 乘以 2用户输入包含加、减、乘、除、括号等计算需求时将表达式整理后传入”。9. 自定义工具开发最佳实践如果你准备把自定义工具应用到真实项目中下面的实践建议值得认真对待。9.1 描述要具体不要只说“是什么”工具描述应该包含三部分工具的用途、触发条件、参数填写规则。最好给出一个示例。模型对示例的敏感度很高一个精心写的示例往往比长篇说明更有效。9.2 返回结果要精简、结构化工具返回值最终会拼接到上下文中继续传给模型。如果返回几万行日志模型不仅处理速度慢还可能被无关信息干扰。更推荐的做法是工具内部做好裁剪、汇总和格式化返回给模型的是一句话或一份结构化摘要。9.3 工具内部必须做参数校验模型生成参数时也可能出错。不要假设参数一定合法。在工具函数入口处做好类型校验、范围校验和异常捕获避免把异常直接抛出导致整个智能体崩溃。9.4 谨慎处理有副作用的操作如果工具涉及发送邮件、写入数据库、删除文件、调用付费接口等操作必须设置权限边界。更稳妥的做法是把操作设计成“先生成操作内容、用户确认后再执行”或者至少记录完整的操作日志。9.5 给工具设置超时和重试调用外部 API 时可能遇到网络波动。工具内部可以设置合理的超时时间、重试次数和兜底返回。这样模型拿到的始终是一段可读的结果而不是一个无意义的异常堆栈。9.6 用日志记录每次工具调用在开发阶段把用户输入、模型选择、参数、执行结果、最终回答全部打印或写入日志。这能极大提升调试效率。生产环境则需要对日志做脱敏处理避免敏感信息泄漏。9.7 控制工具数量避免“选择困难”不是工具越多越好。一个智能体挂载几十个工具时模型反而更容易选错。如果工具数量持续增长可以考虑按业务领域拆分成多个智能体每个智能体只维护自己领域内的少量工具。10. 总结与下一步学习建议自定义工具是 AI 智能体开发的“基本功”。本文围绕厦门大学林子雨老师课程中的 8.8.3 节“自定义工具实操”展开把工具原理、本地最小示例、真实模型接入、LangChain 快速开发、运行验证、常见问题和最佳实践都梳理了一遍。你可以把本文当作课程实验的配套笔记也可以把它当成一个最小可运行的自定义工具模板。下一步建议你尝试三个方向第一把文章中的get_current_local_time和calculate工具替换成你自己熟悉领域的功能比如读取本地 CSV 文件、查询数据库、调用某个内部接口第二设计一个需要一次调用多个工具才能完成的任务观察模型如何拆解和编排第三研究当前的工具调用协议标准比如 MCPModel Context Protocol把工具从“本地函数”升级为“可复用的标准化服务”。如果这篇文章对你有帮助建议收藏备用。尤其是当你刚开始学 AI 编程与智能体开发时工具这块打通了后面的多工具编排、记忆系统、RAG、多智能体协作才有实质性的基础。写代码的过程中遇到任何报错先看日志再回看第 8 节的排查表格大部分问题都能找到答案。