【LangGraph 2026 核心原理解析】大模型 Tool Calling 机制与使用最佳实践全解

在构建 AI Agent 的过程中，大语言模型（LLM）与外部工具（如 API、数据库、本地脚本）的交互是核心能力。然而，模型本身并不能直接运行 Python 代码，它只能理解文本和结构化的 JSON 数据。

那么，LangGraph 是如何将你的 Python 代码翻译成模型能懂的"说明书"，并将模型的决策转化回 Python 执行的呢？本文将从底层原理到代码实践，为你完整拆解 LangGraph 2026 中 Tool Calling 的工作流。

一、 `@tool` 装饰器的底层魔法：从代码到 JSON Schema

当你在 Python 代码中使用 @tool 装饰器时，LangGraph 框架在背后执行了一次"内省与翻译"操作。它会读取你的代码元数据，并将其打包成符合 OpenAI 等主流模型工具规范的 JSON Schema。

来看一个基础的工具定义：

python 复制代码

from langchain_core.tools import tool

@tool
def get_weather(location: str, unit: str = "celsius") -> str:
    """获取指定位置的天气信息。""" 
    return f"{location} 的天气是..."

这段代码映射到底层发给大模型的 JSON 结构如下表所示：

Python 代码部分	JSON Schema 映射	核心作用
`def get_weather`	`"name": "get_weather"`	唯一标识，模型通过该名称决定调用哪个工具。
`"""获取...信息。"""`	`"description": "..."`	最核心部分。模型通过阅读这段描述来判断触发时机。
`location: str`	`"properties": {"location": {"type": "string"}}`	定义参数名称和数据类型。
`unit: str = "celsius"`	`"properties": {"unit": {"default": "celsius"}}`	定义可选参数及其默认值。
（无默认值的参数）	`"required": ["location"]`	框架自动将没有默认值的参数标记为必填项。

二、工具说明书是如何发送给模型的？

明确一点：工具定义（Tools）与对话消息（Messages）在 API 层面上是分离传输的。

当我们调用 llm.bind_tools([get_weather]) 时，底层并不是把 JSON 拼接到 Prompt 里，而是利用了模型提供商（如 OpenAI、Anthropic、Gemini）原生支持的 API 结构：

messages 参数 ：传输对话上下文，如 [{"role": "user", "content": "北京天气？"}]。
tools 参数：独立传输工具的 JSON Schema。

模型接收到请求后，内部注意力机制会同时扫描这两个参数。如果判定需要使用工具，它会停止生成常规文本，转而返回一个带有 tool_calls 字段的结构化响应。

补充：如果使用不支持原生 Tool Calling 的开源或老旧模型，LangGraph 只能退化为"提示工程 + 强制解析"模式（将 JSON 格式要求写进 System Prompt 并用 JsonOutputToolsParser 解析），但这容易引发幻觉和格式错误，在生产环境中不推荐。

三、 LangGraph 中工具的两种调用方式

在 LangGraph 中，有两种主流的工具接入方式，分别对应不同的定制化需求。

方式 1：快捷构建 (`create_react_agent`)

这是最高级的封装，适合不需要复杂控制流的标准问答 Agent。框架在内部自动帮你构建了节点（Nodes）和边（Edges）。

python 复制代码

from langchain_core.tools import tool
from langgraph.prebuilt import create_react_agent
from langchain_openai import ChatOpenAI

@tool
def get_weather(location: str) -> str:
    """获取指定城市的天气情况。"""
    return f"{location} 今天是晴天，气温 25 度。"

llm = ChatOpenAI(model="gpt-4o")
tools = [get_weather]

# 内部自动调用 bind_tools 并搭建完整运行图
agent = create_react_agent(llm, tools)
response = agent.invoke({"messages": [("user", "北京天气怎么样？")]})
print(response["messages"][-1].content)

方式 2：标准状态图构建 (`StateGraph`) ------ 进阶且最常用

在实际项目中，你往往需要精确控制 Agent 的流程，例如工具执行前加权限校验，或对异常进行特定捕获。这就需要手动搭建状态图。

python 复制代码

from typing import Annotated
from typing_extensions import TypedDict
from langgraph.graph import StateGraph, START, END
from langgraph.graph.message import add_messages
from langgraph.prebuilt import ToolNode, tools_condition

# 1. 定义状态结构
class State(TypedDict):
    messages: Annotated[list, add_messages]

# 2. 绑定工具到模型
llm_with_tools = llm.bind_tools(tools)

# 3. 定义大模型节点
def chatbot(state: State):
    response = llm_with_tools.invoke(state["messages"])
    return {"messages": [response]}

# 4. 初始化图与节点
graph_builder = StateGraph(State)
graph_builder.add_node("chatbot", chatbot)
graph_builder.add_node("tools", ToolNode(tools=tools)) # 内置的工具执行节点

# 5. 定义控制流 (Edges)
graph_builder.add_edge(START, "chatbot")

# 条件路由：检查 chatbot 输出是否包含 tool_calls
graph_builder.add_conditional_edges("chatbot", tools_condition)

# 工具执行完毕后，无条件回传给模型节点，生成最终回答
graph_builder.add_edge("tools", "chatbot")

app = graph_builder.compile()

运行流转解析（以"北京天气怎么样"为例）：

触发模型节点 ：模型收到问题及工具 Schema，返回带有 tool_calls=[{"name": "get_weather", "args": {"location": "北京"}}] 的无内容消息。
条件路由 ：tools_condition 检测到 tool_calls，将控制权交给 tools 节点。
工具节点执行 ：ToolNode 解析参数，在本地执行 get_weather(location="北京")，并将结果封装为 ToolMessage 存入 State。
循环回溯：图流转回模型节点，模型结合此前的"调用决策"和此刻的"工具返回结果"，生成最终的自然语言回复："北京今天是晴天，气温约 25 度"。
结束：再次经过条件路由，未检测到新的 tool_calls，走向 END。

四、进阶：对象形式定义工具的最佳实践

当工具逻辑复杂、参数众多，或需要严格的数据校验时，仅使用 Python 原生类型提示是不够的。行业标准做法是使用 Pydantic 类结合 args_schema 来定义工具。

python 复制代码

from pydantic import BaseModel, Field
from typing import Optional

# 1. 定义参数模型（数据校验层）
class WeatherInput(BaseModel):
    location: str = Field(description="城市名称，例如：北京。必须是标准的城市名。")
    forecast_days: Optional[int] = Field(default=1, description="预测未来几天的天气，默认为 1")

# 2. 将模型绑定到工具
@tool(args_schema=WeatherInput)
def get_detailed_weather(location: str, forecast_days: int) -> str:
    """获取详细的天气预报，支持多天查询。"""
    return f"{location} 未来 {forecast_days} 天的天气是..."

为什么推荐这种写法？

更强的表达能力 ：Field(description="...") 允许你为单个参数提供详尽的 Prompt，显著降低模型参数提取的错误率。
防崩溃校验：如果模型产生幻觉，输入了错误类型的数据（比如把数字传成了中文字符串），Pydantic 会在数据进入核心业务逻辑前直接拦截并抛出错误，LangGraph 的 ToolNode 可以捕获该错误并提示模型重试，极大地提升了系统的鲁棒性。
代码高内聚：实现了"数据结构与校验"和"业务执行逻辑"的解耦。

【LangGraph 2026 核心原理解析】大模型 Tool Calling 机制与使用最佳实践全解