一次 Agent 调用发生了什么#

一个标准工具调用 Agent 通常重复以下循环：

1
用户消息
2
  ↓
3
模型判断下一步
4
  ├─ 不调用工具 → 返回最终答案
5
  └─ 生成工具调用
6
          ↓
7
      校验并执行工具
8
          ↓
9
      把工具结果加入消息
10
          └────────────→ 再次调用模型

create_agent 提供这个循环的标准实现。模型可以连续调用多个工具，也可以根据工具结果修正计划，直到不再产生工具调用。

这不意味着业务系统应该把控制权完全交给模型。模型只适合承担需要语言理解、模糊判断或动态选择工具的步骤；权限检查、金额计算、状态迁移和数据约束仍应由确定性代码控制。

create_agent 负责什么#

LangChain 层主要负责统一和组装：

• 模型调用接口；
• 消息和内容块；
• 工具定义与参数 Schema；
• 系统提示词；
• 结构化输出；
• Middleware；
• 标准 Agent 循环。

LangChain 1.x 推荐从下面的导入路径创建 Agent：

1
from langchain.agents import create_agent

旧项目可能仍在使用 langgraph.prebuilt.create_react_agent 或早期 AgentExecutor。迁移时不应只替换函数名，还要检查动态提示词、自定义状态、模型路由和前后置 Hook 是否已经改为 Middleware 形式。

LangGraph 负责什么#

LangGraph 把一次运行表示为带状态的图。核心概念包括：

create_agent 返回的对象本身运行在 LangGraph 上，因此可以自然获得流式输出、检查点、人在环审批和故障恢复能力。只有当外围拓扑超出标准 Agent 循环时，才需要直接编排 StateGraph。

例如这些场景更适合直接使用 LangGraph：

• 先做固定的输入分类，再路由到不同 Agent；
• Agent 前后必须执行不可跳过的确定性步骤；
• 多条分支需要并行执行后汇总；
• 需要明确的重试节点、补偿节点和人工处理节点；
• 要求从历史 Checkpoint 回放或分叉执行。

最小工具调用 Agent#

下面的示例只提供一个无外部副作用的加法工具。模型名称通过环境变量提供，模型供应商凭据由对应集成按照其官方环境变量读取。

安装依赖：

1
pip install -U langchain langgraph langchain-openai

示例代码：

1
import os
2

3
from langchain.agents import create_agent
4
from langchain.tools import tool
5
from langgraph.checkpoint.memory import InMemorySaver
6

7

8
@tool
9
def add(left: int, right: int) -> int:
10
    """返回两个整数的和。"""
11
    return left + right
12

13

14
model_name = os.environ["LANGCHAIN_MODEL"]
15

16
agent = create_agent(
17
    model=model_name,
18
    tools=[add],
19
    system_prompt=(
20
        "你是一个谨慎的计算助手。需要计算时调用工具，"
21
        "不要自行猜测工具结果。"
22
    ),
23
    checkpointer=InMemorySaver(),
24
)
25

26
config = {
27
    "configurable": {
28
        "thread_id": "calculator-demo",
29
    }
30
}
31

32
result = agent.invoke(
33
    {
34
        "messages": [
35
            {
36
                "role": "user",
37
                "content": "请计算 37 加 58，并说明结果。",
38
            }
39
        ]
40
    },
41
    config=config,
42
)
43

44
print(result["messages"][-1].content)

运行前设置模型名称和对应供应商要求的凭据。例如：

1
export LANGCHAIN_MODEL="<provider>:<model>"

示例没有把凭据作为函数参数或源代码常量保存。生产服务还应通过密钥管理系统注入环境变量，而不是把 .env 文件提交到仓库。

Checkpointer 与 thread_id#

只传入 checkpointer 还不够。调用时还需要提供稳定的 thread_id，运行时才能找到同一条任务线的历史状态。

1
config = {
2
    "configurable": {
3
        "thread_id": conversation_id,
4
    }
5
}

需要注意：

• 同一个 thread_id 会继续同一条状态线；
• 新的 thread_id 会创建新的状态线；
• InMemorySaver 只适合本地演示和单进程测试；
• 多进程、容器重启或跨实例恢复需要持久化 Checkpointer；
• thread_id 不是权限凭据，读取状态前仍要校验当前用户是否有权访问该线程。

Checkpoint 让系统能从已保存状态恢复，但不会自动让外部副作用具备事务性。如果某个工具在保存 Checkpoint 前已经调用了第三方接口，重试时仍可能重复执行，因此工具本身需要幂等键或去重机制。

什么时候使用哪一层#

一个实用判断方式是：如果流程能够用稳定的条件分支完整描述，并且模型不需要理解自然语言上下文，就优先写普通代码。

工具设计边界#

1
@tool
2
def lookup_order(order_id: str) -> dict[str, str]:
3
    """读取一个订单的公开状态，不执行修改。"""
4
    ...

版本与依赖管理#

Agent 框架接口变化较快。项目中应固定直接依赖的兼容范围，并在升级时运行针对工具调用、结构化输出、Checkpointer 和 Middleware 的测试。

推荐记录：

1
Python 版本
2
langchain 版本
3
langgraph 版本
4
模型集成包版本
5
模型名称
6
工具 Schema 版本
7
Checkpoint 存储实现

不要根据一段历史 Notebook 输出判断当前接口是否仍然有效，应以当前官方迁移指南和 API 文档为准。

生产环境检查清单#

1
1. 这个流程是否真的需要模型动态决策
2
2. 工具参数是否经过结构化校验和权限检查
3
3. 读工具与写工具是否采用不同的审批策略
4
4. 每个外部请求是否有连接和读取超时
5
5. 工具是否支持幂等或业务去重
6
6. 是否限制最大步骤、运行时间和费用
7
7. 生产环境是否使用持久化 checkpointer
8
8. thread_id 是否和租户、用户权限正确绑定
9
9. 是否记录模型调用、工具调用、审批和错误
10
10. 框架升级后是否运行端到端回归测试

官方参考#

• LangChain v1 更新说明
• LangChain v1 迁移指南
• LangChain Agents
• LangGraph Persistence

本文根据早期个人笔记重新整理，并结合当前官方文档进行了校对。