LangChain贡献：新工具集成

可视化演示

演示新工具实现BaseTool接口规范、适配器将外部API转换为LangChain接口，以及集成测试覆盖正常与异常场景。

工具基类与接口

小C抱着他的智能炒菜机来到“AI厨房”门口，管理员递给他三样东西：统一电源插头标准、电器铭牌模板、安全参数检测表。“你这机器再智能，也得先能插上我们厨房的电路，大家才知道怎么用它。”管理员说。这三样东西，对应到 LangChain 里就是 BaseTool 基类、工具的 name 与 description、以及基于 Pydantic 的参数校验。

技术上的第一步，是让你的工具实现 BaseTool 协议。基类要求你提供三个关键信息：工具叫什么（name）、是干什么的（description）、以及动手干活时执行什么逻辑（_run 或 _arun）。LangChain 之所以要用基类规范，就是为了让五花八门的工具——查天气的、发邮件的、算数学的——都能被同一套机制识别和调度。你不需要从零写适配器，因为社区已经替你铺好了路。

名称和描述是模型“看懂”你的工具的灵魂。名称要短小精准，描述要写清楚适用场景和典型问题，因为大模型是通过字符串来匹配工具的。参数校验则是给工具装一道安全阀：食材列表不能为空、时间不能为负、超过两小时就太慢——这些约束用 Field 的 ge、le、min_length 声明，模型在生成调用参数时就会自动遵守。缓存机制则可以避免同样的输入重复执行昂贵的工具调用，就像把常做的菜提前备好料。

一句话回扣：BaseTool 协议就是那根全厨房通用的插头，name 和 description 是贴在机器上的铭牌，Pydantic 校验是上岗前的安全检测。这三样齐了，你的炒菜机才算拿到了进厨房的入场券。

from langchain_core.tools import BaseToolfrom pydantic import BaseModel, Field class DishInput(BaseModel):    ingredients: list[str] = Field(description="冰箱里现有的食材")    max_time: int = Field(default=30, ge=5, le=120, description="可用的烹饪时间(分钟)") class SmartStirFry(BaseTool):    name = "smart_stir_fry"    description = "根据食材推荐家常菜，当用户问'XX能做什么菜'时调用"    args_schema = DishInput     def _run(self, ingredients: list[str], max_time: int = 30) -> str:        return f"建议做{ingredients[0]}炒蛋，{max_time}分钟内完成"

集成流程规范

设备通过了检测，但想正式进入厨房还得走流程。管理员拿出一份《社区厨房设备引进手册》：先提交设备申请（提 Issue），再附上设计图纸和测试报告（Pull Request），管理者会检查你的设备会不会影响现有的水电管线（依赖管理），然后帮你包装成厨房标准接口（接口封装），最后登记进设备名录（注册与发现）。这一套流程在 LangChain 社区中每天都在发生。

开源贡献的规范要求你的 PR 有清晰的标题、描述和测试用例。依赖管理讲究“轻量原则”：新工具尽量只用标准库或核心依赖，别为一个小功能拖进来一卡车重型库——就像一个新厨具不该让整个厨房重新拉一条高压电线。接口封装是把你的函数包装成 LangChain 认识的模样：用 @tool 装饰器是捷径，它会自动读取函数的 docstring 和类型注解生成 schema。

注册与发现则有两层：如果你希望在模型对话中被自动调用，就把工具通过 bind_tools() 绑定到模型上；如果你想贡献给社区，工具会统一收录进 LangChain 的官方工具列表。社区还有 ToolNode、Agent 等机制来管理多个工具的路由。整个流程的终点，是新工具可以被任何使用 LangChain 的开发者一行代码发现并导入。

回顾一下：申请（Issue）、画图纸（PR）、检查水电（依赖）、统一接口（封装）、登记入库（注册），这五步走完，你的炒菜机就从“个人发明”变成了“厨房公共资产”。

from langchain_core.tools import tool @tooldef query_weather(city: str) -> str:    """查询指定城市的实时天气，当用户询问天气时使用。"""    return f"{city}今天晴，25℃，适合出门"

调用机制

机器正式上岗了。可大厨（LLM）究竟怎么用它？这就要讲清楚厨房里的“点单—传话—出菜”配合机制了。客人说“来盘番茄炒蛋”，大厨不会亲自去切菜——他会看一眼设备名录，发现你的炒菜机适合干这活，于是把任务写成一张标准工单（JSON），递给设备（工具），设备完成后把菜品端回来，大厨再装盘端给客人。这一来一回，就是一次完整的调用链。

调用链的细节是：用户的提问变成消息列表传入模型；模型判断该调用工具，不会直接回答，而是输出一个 tool_calls 指令；LangChain 运行时捕捉到这个指令，把参数交给你的工具执行；工具返回结果后，运行时会带着结果再次请求模型，让模型生成最终回答。如果不需要工具，模型就直接回答。你可以用 RunnableLambda 插入中间逻辑，或者用 AgentExecutor 编排多轮调用。

流式输出（Streaming）是提升体验的关键：既然炒菜需要时间，能不能先让厨房告诉客人“已接单，正在炒”？LangChain 的 .stream() 方法和 astream_events 可以逐字返回模型思考过程，也能以事件流的形式暴露工具调用的每个阶段，让用户实时看到进度。重试机制则像菜没炒好再炒一次——可以用 with_retry() 或 Tenacity 给工具调用套上重试策略。运行配置则包括 temperature、max_tokens、timeout 等运行参数，相当于给大厨设定“出菜速度偏好”。

一个常见的理解偏差是认为“模型直接调用了我的 Python 函数”。实际上模型只负责生成调用意图，真正的执行是在 LangChain 运行时中完成的。理解了这个分工，你就明白为什么工具参数 schema 如此重要——工单写得规范，设备才能零误差地照做。

错误处理

晚市高峰，你的炒菜机突然过热报警——ToolException 被抛了出来。如果厨房没有应急预案，这单菜就砸了，还可能影响后面十桌客人。错误处理，就是为工具运行准备的那套应急预案。

LangChain 推荐的异常处理策略是“分类处置”。工具可能抛出三类异常：输入类错误（厨师传错参数）、执行类错误（设备本身故障）、超时类错误（炒太久了）。针对不同类别，处理方式完全不同：输入错误要让模型知道参数写错了，可以返回一段友好提示让模型自己修正；执行错误则需要尝试重试或降级；而超时错误往往是环境问题，考虑加大 timeout 或改用异步执行。

优雅降级在智能厨具里格外重要：炒菜机坏了，可以马上换一口普通炒锅顶上，虽然效果差一点，但至少客人不用饿着。在代码里，这体现在 try-except 结构中返回一个“备选答案”而非直接崩溃。错误重试应注意指数退避——连续失败三次就停下来检查，而不是疯狂空转。日志追踪则是厨房的监控录像：用 logger 记录每次调用的输入、输出、耗时和异常堆栈，出问题了能精准定位是哪一环节掉了链子。

完善的错误处理，意味着你的工具在大模型这个“有时候不太靠谱的厨师”手上，依然不会搞砸整桌菜。

性能优化

厨房营业越来越火，排队的人越来越多。此时你要考虑的不是再加一台炒菜机，而是优化整个厨房的动线。并发控制如同增加灶台——max_concurrency 参数让多个工具调用并行执行；但也要注意限流，避免把下游 API 压垮。

工具的上下文开销是性能优化的核心命题。每次模型决定是否调用工具时，所有已注册工具的 name、description、参数 schema 都会被翻译成 token 塞进上下文：

这个公式揭示了三条优化方向：控制工具数量、精简描述文案、减少不必要的多轮往返。缓存复用对应着“提前备菜”：相同的参数输入直接命中缓存，跳过执行。批量调度则是“一锅炒三份”——将多个相似请求合并成一次工具调用，或者用 map 批量处理。监控诊断离不开 LangSmith 这类工具，它会记录每次调用的延迟、token 用量和成本，让你一眼看出哪个工具是“电老虎”。

记住，性能优化的顺序永远是：先监控找瓶颈，再针对性优化，最后回归测试。别一上来就给整个厨房换全新的电路。

测试与发布

一切就绪，最后的关卡是质检与上市。再天才的厨具发明，也要经历“单锅试火 → 全宴演练 → 写入菜谱 → 正式上菜单”四步，才能让全社区的客人放心点单。对应到工程实践上，就是单元测试、集成测试、文档编写和语义化版本发布。

单元测试针对工具自身：传入好参数、坏参数、边界值（比如空食材列表、时间为5分钟），断言返回结果符合预期。集成测试则把工具放进完整的 Agent 链路中，模拟真实对话验证“模型能正确生成 tool_calls、工具能正确执行、结果能正确回填”。文档示例是给后来者看的“菜谱”——写明工具的功能、参数含义、一个可运行的示例，让其他开发者照着一试就能跑起来。发布时请遵循 [Semantic Versioning](2)：新增工具用 minor 版本号递增，破坏性修改才升 major 版本。

质量过硬的 PR 会让维护者们放心合并；一个带着完整测试和文档的贡献，比一百行孤零零的代码珍贵得多。你的炒菜机终于印上了厨房的官方认证标志——现在，全社区都能用它给客人做菜了。

---

# test_smart_stir_fry.pydef test_normal_input():    tool = SmartStirFry()    result = tool.invoke({"ingredients": ["番茄"], "max_time": 25})    assert "番茄炒蛋" in result def test_invalid_input():    tool = SmartStirFry()    try:        tool.invoke({"ingredients": [], "max_time": 1})        assert False, "应抛出参数校验异常"    except Exception:        pass

AI 应用场景

Python 演示

"""集成一个"智能炒菜机"工具到 LangChain，并走一遍完整调用链。"""from typing import List, Optionalfrom pydantic import BaseModel, Fieldfrom langchain_core.tools import toolfrom langchain_openai import ChatOpenAIfrom langchain_core.messages import HumanMessage  class DishInput(BaseModel):    ingredients: List[str] = Field(        description="冰箱里现有的食材列表",        min_length=1,    )    max_time: int = Field(        default=30, ge=5, le=120,        description="期望完成的最长时间（分钟）",    )  @tool("smart_stir_fry", args_schema=DishInput,      description="根据现有食材推荐家常菜。"                  "当用户询问'XX能做什么菜'或'怎么吃'时使用。")def smart_stir_fry(ingredients: List[str], max_time: int = 30) -> str:    """根据食材推荐一道简单家常菜做法。"""    main = ingredients[0].strip()    return f"建议做{main}炒蛋：先热锅炒{main}，加蛋液翻匀，{max_time}分钟内出锅。"  def run():    llm = ChatOpenAI(model="gpt-4o", temperature=0.2)    agent = llm.bind_tools([smart_stir_fry])    query = "冰箱里有番茄和鸡蛋，帮我做个快菜"    messages = [HumanMessage(content=query)]    resp = agent.invoke(messages)    if resp.tool_calls:        call = resp.tool_calls[0]        print("模型生成了工具调用请求：", call["name"])        print("参数：", call["args"])        result = smart_stir_fry.invoke(call["args"])        print("工具返回：", result)    else:        print("模型直接回答：", resp.content)  if __name__ == "__main__":    run()

1. @tool("smart_stir_fry", args_schema=DishInput, ...)装饰器把普通函数包装成 LangChain 工具，并绑定参数校验模型
2. class DishInput(BaseModel)用 Pydantic 声明参数结构，模型生成的参数会先在这里通过校验
3. description="根据现有食材推荐家常菜..."这是模型判断“何时该用这个工具”的唯一依据
4. agent = llm.bind_tools([smart_stir_fry])将工具登记到模型上，让它“知道”这个工具的存在
5. resp.tool_calls模型输出中携带的调用指令，包含工具名和参数
6. smart_stir_fry.invoke(call["args"])执行工具并传入模型生成的参数，获得实际结果

常见误区

面试题