LangChain 实战教程：手把手构建具备工具调用能力的智能体

抛弃幻想，准备战斗。

• 适合场景：标准化 RAG 应用、自动化运维指令执行、具备复杂参数约束的 API 编排。

本文解决的问题：Query 意图锁定

• 如何将一个“只会聊天”的模型改造成具备物理行动能力的 AI 智能体？
• 面对多个相似工具，如何通过 Description 优化提升模型的选择准确率？
• 如何在不重跑全量 Prompt 的前提下，让 Agent 记得上一步的操作结果？
• 当外部 API 返回错误或格式不标准时，如何驱动 Agent 进行自动重试与反思？
• 如何在分布式环境下实现 Agent 会话记忆的持久化存储？

目标读者画像：谁应该深度阅读？

• 全栈开发者：想在现有业务中引入 AI 自动化能力，提升系统交互的深度。
• AI 工程师：需要掌握 LangChain 框架中最核心的 Agent 组件及其底层运行循环。
• 初学者：想通过一个完整的、可运行的 Python 案例快速上手智能体开发。

一、 Xiaobai’s Note

最近在贵阳的家里折腾个人提效工具，发现单纯靠 LLM 聊天已经满足不了我的自动化需求了。作为一名全栈小白，我深知“工具”的重要性。如果说普通的 LLM 是一个博学但没手没脚的“大脑”，那么 AI Agent 就是给大脑装上了外骨骼。今天，我带你深入 LangChain 的核心，手把手构建一个真正具备实战能力的智能体。这不是那种简单的 Demo，而是包含了 Pydantic 校验、内存管理和工业级错误处理的干货。

二、⚙️ AgentExecutor 的本质是受控的 Reasoning-Action 推理闭环

传统的程序是预定义的路径，而 Agent 是动态的寻优。 AgentExecutor 的底层运行逻辑如下：

1. 推理：将输入与思考痕迹 (Scratchpad) 发送给 LLM。
2. 决策：LLM 返回 AgentAction（调用工具）或 AgentFinish（直接回答）。
3. 行动：Executor 找到对应 Tool，传入参数并拦截执行。
4. 观察：将执行结果存入中间步骤，并再次喂回模型，直到达成终态。

三、 :📊

| 特性 | 传统 LLM | LangChain Agent | | : | : | : | | 知识时效 | 仅限于训练截止日期 | 可通过搜索工具获取最新信息 | | 计算能力 | 易产生数学幻觉 | 可调用物理计算器、代码解释器 | | 任务深度 | 单次问答，路径固定 | 自主规划并执行多步复杂任务 | | 交互性 | 被动响应文字 | 主动操作数据库、文件系统、API | | 适用场景 | 创意写作、简单问答 | 自动化运维、复杂数据审计、私人助手 |

四、 三 :💻 实战：基于 Pydantic 的强类型工具定义

# 2026 生产级工具定义示例
from langchain.tools import tool
from pydantic import BaseModel, Field

class WeatherInput(BaseModel):
    location: str = Field(description="城市名称，例如：贵阳, 北京")
    unit: str = Field(default="celsius", description="温度单位")

@tool("get_weather", args_schema=WeatherInput)
def get_weather(location: str, unit: str = "celsius") -> str:
    """查询指定城市的实时天气。用于判断是否适合户外运动。"""
    # 物理执行逻辑...
    return f"{location} 当前气温 22 {unit}，天气晴朗。"

实战避坑与报错指南 (Error Logs)

1. Error: Infinite Loop via Overlapping Descriptions
   • 现象：两个工具（如“查询数据库”和“查询日志”）描述太接近，Agent 在两者间反复横跳。
   • 对策：在 description 中明确区分适用边界，并给出具体的 Example 示例。
2. Error: ShellTool Security Risks (删库跑路)
   • 原因：Agent 被诱导执行了 rm -rf / 等危险指令。
   • 对策：小白强烈建议在隔离的 Docker 容器 内运行 Agent 进程，并对 ShellTool 启用严格的指令白名单过滤。
3. Error: Output Parsing Failure
   • 对策：启用 handle_parsing_errors=True，并自定义报错提示词，引导模型重新生成符合 JSON 规范的输出。

七、 常见问题解答

Q: 为什么我的 Agent 总是陷入死循环？

A: 检查 max_iterations 参数是否设置，并确认工具返回的结果是否真正推进了任务进度。如果模型觉得 Observation 没用，它会不断重试。

Q: 使用 Agent 会比普通 Chat 贵很多吗？

A: 是的。Agent 每一轮循环都会带上之前的 intermediate_steps，上下文会迅速膨胀。建议对中间节点使用 GPT-4o-mini，只有在涉及高价值决策时才唤醒 Claude 3.5 Sonnet。

推荐深度阅读

• 👉 AI Agent 全栈指南：构建工业级智能体系统的 10 万字实战手册
• 👉 AI Agent 框架深度横评：LangChain vs AutoGen vs CrewAI
• 👉 LangGraph 实战：构建不跑偏 AI Agent 工作流的 3 个设计模式

我最近在持续研究：

• 基于 LangChain 的异步并发工具调度算法
• 持久化 Checkpoint 在大规模 Agent 任务恢复中的应用
• 具备“意图预测”能力的 Prompt 预加载技术

如果你在构建 LangChain Agent 时遇到了无法解析的 JSON 报错，欢迎留言，我们一起在代码里寻找答案。

(本文由小白深度创作，首发于 XBSTACK。字数约 3900 字。发布日期：2026-04-25)