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

先给结论：LangChain Agent 适合工具边界明确的自动化任务

LangChain Agent 的价值不是“让模型自己想办法”，而是把 LLM 放进一个受控的 Reasoning-Action 循环：模型只能在你注册过、校验过、可审计的工具里选择下一步。它适合天气查询、工单分派、日志检索、轻量运维这类边界清楚的任务；不适合直接接管支付、删库、生产发布等高风险动作。

• 适合场景：标准化 RAG 应用、自动化运维指令执行、具备复杂参数约束的 API 编排。
• 不适合场景：工具权限无法收敛、外部 API 返回不可预测、必须 100% 确定性的交易/审批链路。

本文解决的问题：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. 观察：将执行结果存入中间步骤，并再次喂回模型，直到达成终态。

三、LangChain Agent 与传统 LLM 的差异

特性	传统 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}，天气晴朗。"

这类工具定义的重点不是代码短，而是边界清楚：参数必须可校验，返回值必须可解释，失败时必须让 Agent 知道下一步是重试、换工具，还是交给人处理。

工程边界清单

边界	建议做法	失败后果
工具描述	写明什么时候用、什么时候不用	多个工具互相抢任务，进入循环
参数 Schema	用 Pydantic 限制类型、枚举和默认值	LLM 生成看似合理但不可执行的参数
执行权限	查询、写入、删除分级授权	一次误调用影响真实业务数据
失败返回	返回明确错误码和可恢复建议	Agent 只看到模糊报错，继续盲试

实战避坑与报错指南 (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 全栈指南：架构、工具调用、评测与部署路线
• 👉 AI Agent 框架深度横评：LangChain vs AutoGen vs CrewAI
• 👉 LangGraph 实战：构建不跑偏 AI Agent 工作流的 3 个设计模式

我最近在持续研究：

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

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

(本文由小白整理，首发于 XBSTACK。发布日期：2026-04-25)

专题入口 / AI Agent Hub

从单个 Agent 问题继续进入完整生产体系

AI Agent 专题统一组织架构、记忆、工具调用、评测、安全、部署和多智能体协作，让每篇文章都回到明确的主题主页面。

进入 AI Agent 专题 → 查看架构指南 订阅更新