LangChain AI Agent Tutorial：Build an AI Agent Step-by-Step

LangChain AI Agent Tutorial is the best way to start building autonomous systems. This AI agent tutorial explains the architecture of LangChain agents and provides a step-by-step guide to building your first intelligent agent in 2026.

最近在贵阳的家里折腾个人 IP提效工具，发现单纯靠 LLM 聊天已经满足不了我的自动化需求了。作为一名整天和代码打交道的小白全栈工程师，我深知“工具”的重要性。如果说普通的 LLM 是一个博学但没手没脚的“大脑”，那么 AI Agent（智能体） 就是给大脑装上了手脚和感官。

今天这篇文章，我将带大家深入 LangChain 的核心，手把手教你如何构建一个真正具备实战能力的 AI Agent。这不是那种简单的 Demo，而是包含了 Pydantic 校验、内存管理和工业级错误处理的干货教程。

什么是 LangChain Agent（LangChain 智能体）

👉 开头加入：如果你想系统了解 AI Agent 架构，可以阅读《AI Agent 完整指南》。

在 LangChain 的语境下，Agent 是一个使用 LLM 作为推理引擎的系统。它不再是按照预定义的代码逻辑顺序执行，而是根据用户的输入，动态地决定调用哪些工具（Tools）、以什么顺序调用，并根据工具返回的结果不断修正自己的下一步行动。

简单来说，传统的程序是 If-Else 的集合，而 Agent 是 Reasoning-Action（推理-行动） 的循环。

LangChain Agent 架构（Architecture）

要搞清楚如何构建，首先得看懂它的底层骨架。一个标准的 LangChain Agent 架构由以下四个核心模块组成：

1. LLM（核心大脑）：负责理解意图、规划步骤。现在主流推荐使用支持 Tool Calling 的模型，如 GPT-4o、Claude 3.5 Sonnet 等。
2. Agent Executor（运行环境）：这是 Agent 的“工厂车间”。它负责循环调用 LLM，解析输出，执行工具，并将结果反馈回模型，直到任务完成。
3. Tools（工具集）：Agent 可以调用的具体功能函数。可以是搜索引擎、数据库查询、本地文件读写，甚至是你的业务 API。
4. Memory（记忆）：存储对话历史，让 Agent 记得上一步做了什么，避免陷入死循环。

How to Build AI Agent with LangChain（核心实战）

作为一个务实的小白，我们直接进入代码实战阶段。我们将使用最新的 create_openai_tools_agent 方案，这是目前 LangChain 官方最推荐的构建方式。

Step 1：定义任务

我们的目标是创建一个“全能助理”，它能查询实时天气（模拟 API）、计算复杂的数学题，并且能够记住我们的名字。

Step 2：配置 LLM 与 环境

首先，安装必要的包并配置环境变量。

pip install langchain langchain-openai pydantic

import os
from langchain_openai import ChatOpenAI

# 习惯性把 Key 放在环境变量里，安全第一
os.environ["OPENAI_API_KEY"] = "your_key_here"

llm = ChatOpenAI(
    model="gpt-4o",
    temperature=0, # Agent 需要严谨，建议设为 0
    max_retries=2
)

Step 3：添加 Tools（基于 Pydantic 的高级定义）

很多教程只教你用 @tool 装饰器，但在真实的复杂业务场景中，我们需要严格的参数校验。

from langchain.tools import tool
from pydantic import BaseModel, Field
from typing import Optional

# 定义输入 Schema
class WeatherSearchInput(BaseModel):
    location: str = Field(description="城市名称，例如：贵阳, 北京")
    unit: str = Field(default="celsius", description="温度单位：celsius 或 fahrenheit")

@tool("get_weather", args_schema=WeatherSearchInput)
def get_weather(location: str, unit: str = "celsius") -> str:
    """查询指定城市的实时天气。"""
    # 这里模拟一个 API 调用
    if "贵阳" in location:
        return f"贵阳当前天气晴朗，气温 22 {unit}，适合去黔灵山爬山。"
    return f"{location} 的天气数据暂未获取，建议直接看窗外。"

class CalculatorInput(BaseModel):
    expression: str = Field(description="需要计算的数学表达式，例如: 25 * 4")

@tool("custom_calculator", args_schema=CalculatorInput)
def custom_calculator(expression: str) -> str:
    """执行数学运算。"""
    try:
        # 生产环境严禁直接使用 eval，这里仅作演示
        return str(eval(expression))
    except Exception as e:
        return f"计算错误: {str(e)}"

tools = [get_weather, custom_calculator]

Step 4：构建带有记忆的 Prompt

Agent 需要特定的指令才能工作。

from langchain_core.prompts import ChatPromptTemplate, MessagesPlaceholder

prompt = ChatPromptTemplate.from_messages([
    ("system", "你是一个全栈工程师小白开发的智能助手。你必须使用工具来回答问题，如果你不确定，请调用工具确认。"),
    MessagesPlaceholder(variable_name="chat_history"),
    ("human", "{input}"),
    MessagesPlaceholder(variable_name="agent_scratchpad"), # 必须有，用于存储中间推理步骤
])

Step 5：初始化并执行 Agent

这里我们使用 create_openai_tools_agent 和 AgentExecutor。

from langchain.agents import create_openai_tools_agent, AgentExecutor
from langchain.memory import ConversationBufferMemory

# 创建 Agent
agent = create_openai_tools_agent(llm, tools, prompt)

# 创建 Executor
agent_executor = AgentExecutor(
    agent=agent,
    tools=tools,
    verbose=True, # 开启 verbose 可以看到推理全过程
    handle_parsing_errors=True, # 自动处理解析错误
    max_iterations=5 # 防止死循环，这是小白的防坑指南
)

# 执行
response = agent_executor.invoke({
    "input": "我叫小白，帮我算一下 123 乘以 456 是多少？贵阳今天天气怎么样？",
    "chat_history": []
})
print(response["output"])

深度讲解：AgentExecutor 的底层运行循环

很多同学只会调包，一旦 Agent 报错就抓瞎。作为全栈工程师，我们要搞清楚它的 While 循环逻辑。

AgentExecutor 的核心逻辑伪代码如下：

1. 推理阶段：将用户输入和 agent_scratchpad（之前的尝试记录）发送给 LLM。
2. 决策阶段：LLM 返回一个 AgentAction（决定调用工具）或 AgentFinish（直接回答）。
3. 行动阶段：如果是 AgentAction，Executor 会找到对应的 Tool，传入参数并获取结果。
4. 观察阶段：将 Tool 的输出存入 intermediate_steps。
5. 循环：回到第 1 步，将 intermediate_steps 格式化后再次发给 LLM。

为什么小白要强调这个？ 因为如果你的 Tool 返回的内容太长，或者 LLM 的推理陷入了逻辑怪圈，就会导致 Token 爆炸或超时。通过设置 max_iterations 和 max_execution_time，我们可以强行终止失效的循环，保证系统的稳定性。

如何集成 ChatMessageHistory 实现带记忆的智能体

在真正的 Web 应用（比如我正在开发的博客后台）中，我们需要持久化记忆。ConversationBufferMemory 在内存中好用，但断电就丢。我们可以使用 ChatMessageHistory。

from langchain_community.chat_message_histories import ChatMessageHistory
from langchain_core.runnables.history import RunnableWithMessageHistory

# 模拟一个数据库存储
message_history = ChatMessageHistory()

def get_session_history(session_id: str):
    return message_history

# 使用 RunnableWithMessageHistory 包装我们的 agent_executor
agent_with_history = RunnableWithMessageHistory(
    agent_executor,
    get_session_history,
    input_messages_key="input",
    history_messages_key="chat_history",
)

# 第一次交互
agent_with_history.invoke(
    {"input": "你好，我住在贵阳。"},
    config={"configurable": {"session_id": "xiaobai_001"}}
)

# 第二次交互，它应该记得我住在哪
response = agent_with_history.invoke(
    {"input": "我住在哪？"},
    config={"configurable": {"session_id": "xiaobai_001"}}
)
print(response["output"]) # 输出应该包含“贵阳”

LangChain Agent Example：市场趋势分析实战

让我们来看一个更硬核的案例。假设我需要分析最近贵阳的户外装备市场趋势。

1. 搜索工具：调用 Tavily API 获取最新新闻。
2. 分析工具：将搜索结果传给一个专门的总结函数。
3. Agent 逻辑：
   • 用户问：“最近贵阳羽毛球运动火吗？”
   • Agent 推理：我需要搜索贵阳羽毛球的相关新闻。
   • Agent 行动：调用 tavily_search。
   • Agent 观察：搜索到好几条关于贵阳国际羽毛球赛的新闻。
   • Agent 总结：基于这些数据给出深度分析。

这种多步协作的能力，就是 Agent 区别于普通 Chatbot 的核心竞争力。

详细的错误处理（Error Handling）与重试逻辑

在生产环境，API 可能会挂，模型可能会胡言乱语（幻觉）。作为小白，我建议你必须加上以下保险：

1. Tool 层面的 Try-Except：在工具内部捕获异常，返回一个友好的错误字符串给 LLM，让它决定是否重试。
2. AgentExecutor 的重试：利用 handle_parsing_errors=True。
3. 自定义处理逻辑：

def handle_tool_error(error) -> str:
    return f"抱歉，工具调用失败了。错误信息是：{repr(error)}。请尝试换一种方式提问。"

# 在定义工具时指定
@tool("risky_tool", handle_tool_error=handle_tool_error)
def risky_tool(query: str):
    # 可能抛出异常的代码
    raise ValueError("网络超时")

LangChain Agent vs Traditional LLM

特性	传统 LLM	LangChain Agent
实时性	仅限于训练数据	可通过搜索引擎获取最新信息
准确性	容易一本正经胡说八道	可以调用计算器、数据库校验事实
交互性	单次问答	能够自主规划并执行多步复杂任务
适用场景	创意写作、简单问答	自动化运维、复杂数据分析、个人助理

LangChain Agent Best Practices

作为一名踩过无数坑的小白，我总结了这几条金律：

1. Prompt 必须清晰：在 System Message 中明确告诉 Agent 它有哪些工具，什么情况下该用。
2. 工具原子化：一个工具只干一件事。不要写一个“万能工具”，那会让 LLM 困惑。
3. 严格的 Schema：使用 Pydantic 定义输入参数，这是减少 Agent 报错的最有效手段。
4. 监控中间步骤：通过 verbose=True 或 LangSmith 监控推理过程，找出它在哪里“走神”了。
5. 温度控制：Agent 场景下，temperature 建议设为 0，我们不需要它太有“创造力”，我们需要的是精准执行。

FAQ

Q: 我的 Agent 总是陷入死循环怎么办？ A: 检查你的工具描述。如果两个工具的功能描述太接近，LLM 可能会在它们之间反复横跳。另外，务必设置 max_iterations。

Q: 可以让 Agent 调用本地的 shell 命令吗？ A: 可以，LangChain 提供了 ShellTool。但小白强烈建议在 Docker 容器里运行，否则万一 Agent 发疯执行了 rm -rf /，你就得重装系统了。

Q: 使用 Agent 会不会很贵？ A: 是的。Agent 因为需要多次循环调用 LLM，且每次循环都会带上之前的中间推理记录，Token 消耗会比普通聊天快得多。建议在生产环境使用更精准的 Prompt 或者微调模型。

构建 AI Agent 是一场关于“控制”与“释放”的艺术。我们释放了 LLM 的推理能力，但必须通过像 LangChain 这样的框架来控制它的执行边界。

扩展阅读与 Topic Cluster (Internal Links)

掌握了 LangChain 构建，你就拿到了 AI Agent 开发的入场券。建议继续深入以下模块：

• 🏆 核心入口：AI Agent Complete Guide (2026)：全栈开发完全指南
• 🏗️ 架构解析：AI Agent Architecture Guide：智能体物理架构深度指南
• 🧠 任务规划：AI Agent Planning Tutorial：任务拆解与推理环实战
• 🔌 标准协议：MCP Protocol Tutorial：AI Agent 的标准通信协议
• 🤖 协作系统：Multi-Agent Systems Guide：多智能体协作与架构设计

作为一名在贵阳努力学习 AI 的小白，我坚信未来每个程序员都会拥有自己的 Agent 军团。如果你在实战中遇到任何问题，欢迎在评论区留言，我们一起在代码里寻找答案！

---

本文由 AltStack 首席博主“小白”原创。如需转载，请注明出处，并保留所有内链。