2026 年 LangChain Agents 完整指南：已按 LangGraph 时代更新

LangChain Agents 实际如何工作（2026 架构）

旧模型：AgentExecutor

AgentExecutor 是最早的编排层。你会定义一个 agent（LLM + prompt），挂上工具，然后 executor 运行循环。它能工作，但有真实限制：

• 状态控制有限：很难在执行中暂停、分支或恢复
• 多智能体支持较弱：不是为 orchestrator/subagent 模式设计的
• 失败模式不透明：生产中经常出现静默错误

当前模型：LangGraph Agents

从 LangChain v0.3+ 开始，LangGraph 是构建 agents 的推荐方式。LangGraph 把 agent 循环建模成显式状态机：一个有向图，其中每个节点是函数，边表示条件转换。

这很重要，因为：

• 你可以在循环中的任何位置检查和修改状态
• 分支逻辑（例如“如果工具失败，尝试 fallback”）是一等能力
• 多智能体系统可以自然地组合为嵌套 graphs
• Human-in-the-loop 中断非常容易添加

两种方式仍都在使用。它们的对比如下：

用真实示例解释 ReAct 模式

ReAct（Reason + Act） 是大多数 LangChain agents 背后的核心范式。LLM 不只是回答，它会在每次行动前叙述自己的推理。

对于查询 “What's the current price of GPT-4o API calls and how much would 1 million tokens cost?”，真实 ReAct trace 如下：

每一步在 LangSmith 中都会显示为独立 span。这对调试非常关键，尤其是工具返回垃圾数据或 LLM 误解 observation 时。

AgentExecutor vs. LangGraph Agents：2026 年该用哪个？

LangChain 自己的文档写道：“We recommend that new projects use LangGraph for agent workflows.” 这是直接信号，而不是随口建议。

15 分钟构建你的第一个 LangChain Agent（逐步教程，2026 API）

这里使用 LangChain v0.3+ 和 LangGraph。所有代码都附有说明。

步骤 1：安装依赖

pip install langchain langchain-openai langgraph langsmith tavily-python

步骤 2：设置环境变量

import os
os.environ["OPENAI_API_KEY"] = "your-key"
os.environ["TAVILY_API_KEY"] = "your-key"
os.environ["LANGCHAIN_API_KEY"] = "your-key"      # for LangSmith tracing
os.environ["LANGCHAIN_TRACING_V2"] = "true"       # enable tracing
os.environ["LANGCHAIN_PROJECT"] = "my-first-agent"

步骤 3：定义工具和模型

from langchain_openai import ChatOpenAI
from langchain_community.tools.tavily_search import TavilySearchResults
from langgraph.prebuilt import create_react_agent

# Define the tools the agent can use
tools = [TavilySearchResults(max_results=3)]

# Bind the model - gpt-4o works well for tool-calling agents
model = ChatOpenAI(model="gpt-4o", temperature=0)

步骤 4：创建并调用 agent

# create_react_agent is the 2026 idiomatic way - no AgentExecutor needed
agent = create_react_agent(model, tools)

# Invoke with a message
result = agent.invoke({
    "messages": [("human", "What are the top 3 AI agent frameworks in 2026?")]
})

# The final answer is the last message in the response
print(result["messages"][-1].content)

这就是一个可工作的 agent。它会搜索网页、推理结果，并返回有依据的答案，代码不到 20 行。

向 Agent 添加自定义工具

@tool 装饰器会把任何 Python 函数包装成 LangChain 兼容工具。docstring 会成为工具描述，一定要写好，因为 LLM 会读它来决定何时调用该工具。

from langchain_core.tools import tool
import requests

@tool
def get_domain_authority(domain: str) -> dict:
    """
    Look up the Domain Authority (DA) score for a given domain.
    Use this when the user asks about SEO metrics or site authority.
    Returns DA score, spam score, and backlink count.
    """
    response = requests.get(
        f"https://api.yourseotool.com/da?domain={domain}",
        headers={"Authorization": "Bearer YOUR_TOKEN"}
    )
    return response.json()

# Add to your agent's tool list
tools = [TavilySearchResults(max_results=3), get_domain_authority]
agent = create_react_agent(model, tools)

使用 LangSmith 开启可观测性

设置 LANGCHAIN_TRACING_V2=true 就够了。之后每次 agent 运行都会以 span 树形式出现在 LangSmith dashboard 中。

如何阅读 trace 来调试失败：

1. 在 LangSmith 中打开失败运行
2. 找到发生错误的 tool call span
3. 检查 inputs：LLM 是否传入了正确参数？
4. 检查 outputs：工具是否返回错误或意外格式？
5. 检查 next Thought：LLM 是否正确理解 observation？

一个常见模式：工具把 429 rate-limit 错误作为字符串返回，LLM 把它当作有效数据，最终答案就会幻觉。LangSmith 能在几秒内让这一点可见。没有它，你只能读原始日志，希望找到 bug。

真实 LangChain Agent 使用场景（含完整示例）

使用 LangChain 构建多智能体系统：一个 Agent 不够时

单个 agent 会遇到真实限制：长任务会撑爆上下文窗口，工具列表太大会让选择不可靠，而且无法并行化。

解决方案：使用一个 orchestrator agent 把任务拆成子任务，并委派给专门子 agents。在 LangGraph 中，subagents 只是父 graph 中的节点。orchestrator 使用 Send 将工作并行分发给 subagents 并收集结果。

LangChain vs. CrewAI vs. AutoGen vs. LangGraph：聚焦对比

根据你的情况选择正确 Agent 模式

常见 LangChain Agent 失败以及如何修复

以下是你会在生产中遇到的五类失败，以及真正的修复方式。

常见问题

最终结论：2026 年 LangChain Agents 仍然值得吗？

值得，但有一个重要前提。

LangChain 的生态优势是真实存在的。工具集成、社区、文档以及 LangSmith 可观测性工具合在一起，目前仍然难以匹敌。如果你在生产中构建任何接触 LLM 的东西，LangSmith + LangGraph 的组合是当下最成熟的调试和编排方案。

前提是：LangChain 的 API 变化曾经非常剧烈。如果你曾被破坏性变更伤过，这种挫败感是合理的。随着 v0.3，代码库已经稳定很多，但你仍应该锁定依赖，并在升级前阅读 changelog。

Agent 时代并没有放慢。LangChain 决定把 LangGraph 作为生产原语，是正确选择；2026 年正是这个选择开始兑现的一年。