目录
1. Agent
1.1 ReAct 模式：Agent 的“思考-行动-观察”循环
1.2 Agent vs Graph
1.3 何时用 Agent，何时用 Graph？
1.4 Graph 作为 Agent 的工具
2. LangChain v1.0 核心特性
2.1 create_agent
Agent 状态结构：AgentState
2.2 中间件（Middleware）
2.3 基于 LangGraph 的开箱即用能力
2.4 标准化消息内容块（content_blocks）
3. LangChain v1.0 迁移指南
4. 实战代码片段：一个完整的智能天气 Agent
1. Agent
Agent（智能体） 是一个将大语言模型（LLM）与工具（Tools）相结合的系统，它能够对任务进行推理，自主决定使用哪些工具，并迭代地朝着最终目标努力
简单来说：
Agent = LLM（推理引擎） + 工具（执行能力） + 控制循环（自主决策）
一个 LLM Agent 在循环中运行工具以达成目标，直到模型输出最终结果或达到迭代上限等
在 LangChain 中，Agent 是基于 LangGraph 构建的图式智能体——在 LangGraph 中，一个 Graph 由节点和边组成，其定义了 Agent 如何处理信息。Agent 在图中移动，依次执行模型节点（调用 LLM）、工具节点（执行工具）或中间件等
1.1 ReAct 模式：Agent 的“思考-行动-观察”循环
ReAct（Reasoning + Acting）模式是 LangChain Agent 的基石。其循环如下：
用户输入 → Agent 解析意图 → 推理决策 → 调用工具 → 获取反馈 → 判断是否完成？ ↙ ↘ 完成：返回结果 未完成：继续循环- Reason（推理）：LLM 分析当前状态，决定下一步该做什么
- Act（行动）：调用工具或生成最终答案
- Observe（观察）：获取工具返回结果或环境反馈
- 重复直到满足停止条件（模型输出最终消息或达到迭代上限）
自我纠错能力：当工具返回错误时，Agent 会重新进入推理阶段，调整参数后重试
1.2 Agent vs Graph
| 维度 | Agent（智能体） | Graph（流程图） |
|---|---|---|
| 决策权 | LLM 自主规划与决策 | 开发者预定义流程 |
| 确定性 | 行为不确定，依赖模型推理 | 路径确定，可预测 |
| 适用场景 | 开放式问题、多步骤任务、需要动态调整 | 固定业务流程（如“录音→转写→总结→保存”） |
| 典型例子 | 通用问答助手、自动编码 Agent | 视频生成流水线、数据报表生成 |
1.3 何时用 Agent，何时用 Graph？
用户任务分析 │ ├─ 任务路径完全确定？ ──是──→ 使用 Graph（保证一致性和效率） │ ├─ 需要多轮对话、动态决策？ ──是──→ 使用 Agent（发挥 LLM 推理能力） │ └─ 有确定性子流程，但整体不确定？ │ └─→ Agent + Graph 组合：Agent 负责高層规划，Graph 作为 Tool 执行固定步骤1.4 Graph 作为 Agent 的工具
在实际企业应用中，常将整个 Graph 封装为一个 Tool，供 Agent 调用。例如：
- 用户说“生成上周销售周报”
- Agent 识别意图 → 调用“周报生成 Graph”（拉取数据 → LLM 分析 → 图表渲染 → 输出）
- 整个过程对用户而言是一次对话，但底层是 Graph 保障的稳定性
2. LangChain v1.0 核心特性
2.1 create_agent
from langchain.agents import create_agent- 参数总览
| 参数 | 类型 | 必填 | 默认值 | 说明 |
|---|---|---|---|---|
model | str或BaseChatModel | 是 | 无 | 语言模型，支持字符串标识（如"openai:gpt-5.5"）或已初始化的模型实例 |
tools | Sequence[BaseTool | Callable | dict] | 否 | None | 工具列表，支持@tool装饰器函数、Pydantic 模型或字典 |
system_prompt | str或SystemMessage | 否 | None | 系统提示词，定义 Agent 的角色和行为准则 |
middleware | Sequence[AgentMiddleware] | 否 | () | 中间件列表，用于动态提示、摘要、护栏等高级定制 |
response_format | ResponseFormat或type或dict | 否 | None | 结构化输出配置，指定最终输出的 Schema |
state_schema | type[AgentState] | 否 | None | 自定义 Agent 内部状态的结构 |
context_schema | type[ContextT] | 否 | None | 运行时上下文结构，用于在调用时传入额外数据（不持久化） |
checkpointer | Checkpointer | 否 | None | 检查点保存器，实现对话持久化（短期记忆/跨会话记忆） |
store | BaseStore | 否 | None | 长期存储，用于跨会话共享数据（如用户偏好） |
interrupt_before | list[str] | 否 | None | 在指定节点之前暂停执行（人机协同） |
interrupt_after | list[str] | 否 | None | 在指定节点之后暂停执行（人机协同） |
debug | bool | 否 | False | 是否输出详细调试日志 |
name | str | 否 | None | Agent 名称，在多 Agent 系统中作为子图节点标识 |
cache | BaseCache | 否 | None | 缓存配置 |
transformers | Sequence[TransformerFactory] | 否 | None | 流式传输转换器 |
- 更简洁：比 langgraph.prebuilt.create_react_agent 更直观
- 基于标准循环：“调用模型 → 模型选择并执行工具 → 无工具调用时结束”
- 通过中间件定制：动态提示、对话摘要、工具权限控制等，全部通过中间件注入
from dataclasses import dataclass from langchain.agents import create_agent from langchain.tools import tool from langgraph.checkpoint.memory import InMemorySaver from langgraph.store.memory import InMemoryStore @tool def get_weather(city: str) -> str: """获取指定城市天气""" return f"{city}阳光明媚" @dataclass class WeatherResult: city: str description: str agent = create_agent( model="openai:gpt-5.5", tools=[get_weather], system_prompt="你是一位天气预报助手，回答要简洁有趣。", response_format=WeatherResult, checkpointer=InMemorySaver(), store=InMemoryStore(), name="weather_assistant" ) # 第一次对话 config = {"configurable": {"thread_id": "user-123"}} result = agent.invoke( {"messages": [{"role": "user", "content": "上海天气如何？"}]}, config=config ) print(result['structured_response']) # WeatherResult(city="上海", description="阳光明媚") # 第二次对话（自动继承上下文） result = agent.invoke( {"messages": [{"role": "user", "content": "那北京呢？"}]}, config=config # 相同 thread_id )Agent 状态结构：AgentState
| 字段 | 类型 | 说明 |
|---|---|---|
messages | list[AnyMessage] | 消息历史，使用add_messagesreducer 自动合并 |
jump_to | "tools"|"model"|"end"|None | 流程跳转控制（临时） |
structured_response | Any | 结构化输出结果（不参与输入） |
结构化输出会在 Agent 循环结束后额外调用一次 LLM来生成格式化结果
2.2 中间件（Middleware）
中间件让开发者能在模型调用前/后动态修改上下文，通过可组合的抽象实现：
- 动态提示词：根据对话状态动态调整提示
- 对话摘要：过长历史自动压缩
- 选择性工具访问：不同用户不同工具权限
- 护栏（Guardrails） ：敏感信息脱敏
- 人机协同：敏感操作需人工审批
2.3 基于 LangGraph 的开箱即用能力
由于 create_agent 构建于 LangGraph 之上，你无需学习 LangGraph 即可享受：
- 持久化：通过检查点（checkpoint）自动跨会话保存
- 流式传输：实时输出 token、工具调用、推理轨迹
- 人机协同：敏感操作前暂停等待审批
- 时间旅行：回退到任意历史状态探索不同路径
2.4 标准化消息内容块（content_blocks）
不同模型提供商的消息内容返回格式差异巨大。v1.0 引入统一抽象 content_blocks：
类型 (type) | 描述 | 关键属性 |
|---|---|---|
text | 标准的文本输出 | text(str): 文本内容annotations(list[Annotation]): 元数据标注列表，如引用信息 |
reasoning | 模型的推理过程或思维链 | reasoning(str): 推理内容 |
tool_call | 模型发起的工具/函数调用请求 | name(str): 工具名称input(dict): 调用参数id(str): 调用唯一ID |
tool_result | 工具执行后返回的结果 | content(strorlist): 工具执行结果tool_use_id(str): 对应的tool_callID |
image | 图像内容，支持多模态 | url(str): 图像URLmime_type(str): 图像MIME类型或 data(str): Base64编码的图像数据 |
audio | 音频内容 | 属性与image块类似，通过url或data引用 |
video | 视频内容 | 属性与image块类似，通过url或data引用 |
document | 文档内容（如PDF、TXT等） | 属性与image块类似，通过url或data引用 |
server_tool_use | 模型请求使用服务端内置工具（如联网搜索） | name(str): 工具名称input(dict): 调用参数id(str): 调用唯一ID |
web_search_tool_result | 服务端内置工具（如联网搜索）返回的结果 | content(list): 搜索结果列表tool_use_id(str): 对应的server_tool_useID |
non_standard | 暂未被映射到标准块的非标准或供应商特定数据 | value(dict): 包含所有非标准数据的字典 |
for block in response.content_blocks: if block["type"] == "reasoning": # 统一为 reasoning ... elif block["type"] == "tool_call": ...目前支持 langchain-anthropic、langchain-openai、langchain-aws、langchain-google-genai、langchain-ollama
3. LangChain v1.0 迁移指南
以下接口从 langchain 或 langchain-core 直接导出，不再散落各处
| 模块 | 关键类/函数 | 用途 |
|---|---|---|
langchain.agents | create_agent | 创建标准 Agent |
langchain.agents | AgentState | Agent 状态类型，继承自 Graph 状态 |
langchain.tools | @tool | 装饰器定义工具 |
langchain.tools | ToolRuntime | 运行时上下文，用于访问 store/context |
langchain.chat_models | init_chat_model | 统一模型初始化 |
langchain.embeddings | init_embeddings | 统一嵌入模型初始化 |
langchain.messages | 各种消息类型、content_blocks、trim_messages | 消息处理与标准化 |
langgraph.checkpoint.memory | InMemorySaver | 内存检查点（用于短期记忆） |
langgraph.store.memory | InMemoryStore | 内存存储（用于长期记忆） |
迁移注意：旧版链、检索器、索引接口等已移至 langchain-classic 包，如需使用请 pip install langchain-classic 并修改导入路径
更多内容参考迁移指南：https://docs.langchain.com/oss/python/migrate/langchain-v1
4. 实战代码片段：一个完整的智能天气 Agent
from dataclasses import dataclass from langchain.agents import create_agent from langchain.chat_models import init_chat_model from langchain.tools import tool, ToolRuntime from langgraph.checkpoint.memory import InMemorySaver from langgraph.store.memory import InMemoryStore @dataclass class Context: user_id: str @tool def get_weather_for_location(city: str) -> str: """获取指定城市天气""" return f"{city}总是阳光明媚！" @tool def get_user_location(runtime: ToolRuntime[Context]) -> str: """从 store 获取用户位置""" user_id = runtime.context.user_id store = runtime.store store.put(("users",), user_id, {"name": f"name_{user_id}"}) return "北京" if user_id == "1" else "上海" model = init_chat_model("gpt-5.6-luna", temperature=0) checkpointer = InMemorySaver() store = InMemoryStore() agent = create_agent( model=model, system_prompt="你是一位天气预报专家，擅长双关语。", tools=[get_user_location, get_weather_for_location], context_schema=Context, checkpointer=checkpointer, store=store ) config = {"configurable": {"thread_id": "1"}} response = agent.invoke( {"messages": [{"role": "user", "content": "外面天气怎么样？"}]}, config=config, context=Context(user_id="1") ) print(response['messages'][-1].content) # 最终回答- thread_id 实现会话持久化（第二次调用自动继承历史）
- store 实现长期记忆（跨线程存储用户信息）
- context_schema 传递运行时参数
