LangChain Agents：智能体使用完全指南

LangChain Agents是将大语言模型（LLM） 与工具深度结合的智能系统，能够自主推理任务需求、选择合适工具、迭代执行操作，直至达成目标并输出结果。函数提供了生产级的Agent实现，其底层基于LangGraph构建为图式运行时（由「节点/执行步骤」和「边/节点连接」构成），Agent会沿预设的图执行模型调用、工具运行、中间件处理等逻辑，遵循ReAct（Reasoning + Acting，推理+行动） 循环工作，直至满足停止条件（模型输出最终结果/达到迭代次数限制）。

本文将从核心组件、Agent调用、高级概念、核心扩展能力-中间件四个维度，全面解析LangChain Agents的使用方法，所有代码示例均附带逐行详解，同时标注生产环境中的关键注意事项。

Agent的核心能力由模型（推理引擎）、工具（行动载体）、系统提示词（行为准则） 三大组件支撑，三者均支持静态一次性配置（基础开发首选）和运行时动态定制（生产环境复杂需求），是搭建Agent的基础。

1. 模型（Model）：Agent的推理核心

模型是Agent的“大脑”，负责任务推理、工具选择、结果整合，LangChain支持静态模型和动态模型两种配置方式，适配不同开发场景。

1.1 静态模型

创建Agent时一次性配置完成，执行过程中模型保持不变，是最常用、最简洁的方式，支持两种初始化方法，可根据需求选择简洁版或精细配置版。

方法1：模型标识字符串初始化（简洁版）

直接传入厂商+模型的标识字符串，LangChain会自动推断并初始化模型，无需手动导入模型类。

代码详解：

• 导入生产级Agent创建核心函数；
• 模型标识字符串支持自动推断厂商，如直接传入，LangChain会默认解析为；
• 为预定义的工具列表，若传入空列表，Agent将退化为纯LLM节点，无工具调用能力。

方法2：模型实例化初始化（精细配置版）

直接通过模型厂商的包实例化模型类，可自定义、等所有参数，实现生产级的精细化配置。

代码详解：

• 从导入OpenAI的聊天模型类（其他厂商模型需导入对应类，如Anthropic的）；
• 模型实例化支持所有厂商专属参数，实现对模型的完全控制，适配生产环境的稳定性、一致性需求；
• 最终将模型实例传入，替代简洁版的标识字符串。

1.2 动态模型

根据运行时状态/上下文（如对话长度、用户角色、任务复杂度）动态选择模型，实现请求路由优化和成本控制（简单任务用轻量模型，复杂任务用高级模型）。需通过装饰器创建中间件实现，核心是在模型调用前修改请求中的模型实例。

代码详解：

1. 初始化两个不同规格的模型，分别适配简单/复杂任务，实现成本与效果的平衡；
2. 装饰器将普通函数转为模型调用中间件，函数接收（模型请求对象）和（后续处理函数）两个核心参数；
3. 从中获取当前Agent的状态（如对话消息数），作为模型选择的依据；
4. 覆盖请求中的默认模型，执行后续的模型调用逻辑；
5. 创建Agent时，将中间件传入参数，中间件会在模型调用前自动执行。

生产注意事项：使用结构化输出时，不支持预绑定工具的模型（即已调用方法的模型），若需结合动态模型和结构化输出，需保证传入中间件的模型未做工具预绑定。

2. 工具（Tools）：Agent的行动载体

工具让Agent具备执行具体实际操作的能力（如搜索、查天气、计算），LangChain的Agent工具体系远超简单的模型-工具绑定，原生支持：

• 单提示触发多工具序列调用；
• 合适场景下的多工具并行调用；
• 基于前序结果的动态工具选择；
• 工具执行的重试逻辑与错误处理；
• 工具调用间的状态持久化。

工具支持静态定义和运行时动态定制，以下从工具定义、错误处理、ReAct循环使用、动态工具四个方面详解。

2.1 定义工具

工具可定义为普通Python函数或协程，通过装饰器自定义工具名称、描述、参数schema等元数据，LangChain会自动将元数据传递给模型，让模型理解工具的用途和使用方式。

代码详解：

1. 装饰器是LangChain工具定义的核心，会自动为函数添加工具元数据（名称、描述、参数），无需手动配置；
2. 函数的文档字符串是模型识别工具的关键，需简洁清晰地说明工具用途，模型会根据该描述判断是否调用工具；
3. 工具函数支持类型注解（如），LangChain会自动解析为参数schema，限制模型传入的参数类型；
4. 创建Agent时，将工具以列表形式传入参数，支持同时传入多个工具。

基础注意事项：若传入空列表，Agent将仅为纯LLM节点，失去工具调用能力。

2.2 工具错误处理

工具执行过程中可能出现异常（如参数错误、网络问题），可通过装饰器创建中间件，自定义异常处理逻辑，捕获异常后返回给模型，让模型感知错误并做出后续决策（如重试、提示用户）。

代码详解：

1. 装饰器将普通函数转为工具调用中间件，拦截工具的执行过程；
2. 块捕获工具执行的所有异常，避免Agent因工具错误直接中断；
3. 异常时返回，包含自定义错误提示和（工具调用唯一ID），能让模型将错误与对应的工具调用关联，实现精准的错误处理；
4. 中间件挂载到参数，工具执行时会自动触发。

错误返回示例：工具执行触发除零错误时，Agent会返回以下：

2.3 ReAct循环中的工具使用

Agent的核心工作模式是ReAct循环，即推理→行动→观测的迭代过程：模型先推理是否需要调用工具、调用哪个工具，再执行工具获取观测结果，最后将观测结果融入下一轮推理，直至能给出最终答案。

ReAct循环实战示例：查询「当前最受欢迎的无线耳机并验证库存」

1. 人类提问：Find the most popular wireless headphones right now and check if they’re in stock
2. 推理：热度具有时效性，需要调用搜索工具→行动：调用
3. 观测：工具返回热门耳机列表，榜首为WH-1000XM5
4. 推理：需要验证榜首产品的库存→行动：调用
5. 观测：工具返回WH-1000XM5有10件库存
6. 推理：已获取核心信息，可输出最终答案→行动：生成自然语言回答

整个过程中，Agent无需人工干预，自主完成工具选择、调用和结果整合，是ReAct循环的典型应用。

2.4 动态工具

实际开发中，常需要运行时调整Agent的可用工具（而非创建时一次性定义），LangChain支持两种动态工具方案，适配不同的业务场景。

方案1：过滤预注册工具

适用场景：所有可能的工具在Agent创建时已注册，需根据运行时状态/权限/上下文过滤可用工具（如管理员可用所有工具，普通用户仅可用只读工具）。 通过中间件，在模型调用前过滤请求中的工具列表即可实现。

核心逻辑：通过覆盖请求中的工具列表，模型仅能看到过滤后的工具，从而实现权限管控。

方案2：运行时注册工具

适用场景：工具在运行时动态发现/生成（如从MCP服务器加载、根据用户数据生成、从远程注册中心获取），Agent创建时未注册该工具。 需同时实现两个中间件钩子：（将动态工具添加到请求）和（处理动态工具的执行），缺一不可。

代码详解：

1. 先定义动态工具，该工具在Agent创建时不传入参数，属于运行时注册；
2. 自定义类继承，实现两个核心钩子：
   • ：工具调用时，判断是否为动态工具，若是则覆盖请求中的工具，指定动态工具执行，否则按原有逻辑处理；

   ：模型调用前，将动态工具与原有静态工具合并，更新请求的工具列表，让模型“看到”动态工具；

3. 挂载中间件后，Agent可同时使用静态工具和动态工具，实现工具的运行时扩展。

关键注意事项：钩子是必需的，因为Agent无法执行创建时未注册的工具，该钩子让Agent明确动态工具的执行逻辑。

3. 系统提示词（System prompt）：Agent的行为准则

系统提示词用于定义Agent的角色、工作方式、响应规范，是塑造Agent行为的核心，支持静态配置和运行时动态生成，同时可利用模型厂商的专属特性（如Anthropic的提示词缓存）。

3.1 静态系统提示词

直接传入字符串或SystemMessage对象创建静态提示词，字符串为简洁版，为精细版，支持厂商专属特性（如Anthropic的提示词缓存，降低延迟和调用成本）。

方式1：字符串简洁版

方式2：SystemMessage精细版（支持厂商特性）

代码详解：

1. 从导入和，分别用于定义系统提示词和人类提问；
2. 的支持多文本块配置，为每个文本块设置专属属性；
3. 是Anthropic的专属特性，告诉厂商缓存该文本块，当重复使用相同系统提示词时，无需重复传输大文本（如《傲慢与偏见》全本），大幅降低调用延迟和token成本；
4. 该方式适用于系统提示词包含大文本内容且需要重复调用的场景。

基础注意事项：若不传入，Agent会直接从用户消息中自动推断任务目标，适用于简单的通用对话场景。

3.2 动态系统提示词

适用场景：需要根据运行时上下文/Agent状态（如用户角色、任务类型）动态生成系统提示词（如对专家返回技术细节，对新手用通俗解释）。 通过装饰器创建中间件，根据模型请求生成个性化的系统提示词。

代码详解：

1. 用定义运行时上下文schema，指定上下文包含的字段（如），让Agent能解析传入的上下文；
2. 装饰器将普通函数转为动态提示词中间件，从中获取运行时上下文；
3. 根据上下文的生成个性化的系统提示词，实现Agent的自适应响应；
4. 创建Agent时，通过绑定上下文schema，调用时通过参数传入具体的上下文信息。

LangChain Agent的核心调用方式为方法，通过向Agent的状态（State） 传入新消息触发执行，所有Agent的状态中均包含消息序列，这是Agent处理请求的核心依据。

基础调用示例

核心逻辑：方法接收一个字典参数，其中为消息列表，每个消息包含（角色：user/ai/tool等）和（内容），Agent会根据消息序列执行推理和工具调用，返回最终结果。

扩展调用能力

LangChain Agent底层基于LangGraph构建，完全兼容LangGraph的Graph API，除（同步获取最终结果）外，还支持：

• ：流式获取执行过程和结果（详见「高级概念-流式输出」）；
• ：批量处理多个请求；
• /：异步调用方法，适配异步开发框架。

基础的核心组件和调用方式可满足简单开发需求，LangChain还提供了结构化输出、记忆、流式输出三大高级特性，适配生产环境的结果可解析、上下文记忆、实时反馈需求。

1. 结构化输出

实际开发中，常需要Agent返回固定格式的结构化结果（如提取联系人信息、解析数据），而非无格式的自然语言，LangChain通过参数实现结构化输出，提供两种核心策略，适配不同的模型能力。

结构化输出的schema可通过Pydantic BaseModel或dataclass定义，以下以Pydantic为例讲解。

策略1：ToolStrategy（工具调用策略）

核心原理：借助模型的工具调用能力生成结构化输出，将结构化schema转为虚拟工具，模型通过调用虚拟工具输出符合schema的结果。 适用场景：模型不支持厂商原生结构化输出，或原生能力不可靠，该策略兼容所有支持工具调用的模型，通用性最强。

代码详解：

1. 用Pydantic 定义结构化schema，指定字段名和类型，实现数据校验Agent 智能体；
2. 将schema传入，再将其赋值给参数，Agent会自动将schema转为虚拟工具；
3. 调用后，从中获取强类型的结构化结果，可直接通过属性访问（如）。

策略2：ProviderStrategy（厂商原生策略）

核心原理：使用模型厂商的原生结构化输出能力（如OpenAI的、Anthropic的）生成结果，无需借助工具调用。 适用场景：模型支持厂商原生结构化输出，该策略更高效、更可靠，是生产环境的首选。

代码详解：仅需将替换为，其余逻辑与工具调用策略一致，Agent会自动调用厂商的原生结构化输出能力。

LangChain 1.0 版本简化特性

在LangChain 1.0及以上版本中，无需手动指定策略，直接传入schema即可：

Agent会自动检测模型能力：若模型支持原生结构化输出，默认使用；若不支持，自动回退为，大幅简化开发。

2. 记忆（Memory）

Agent默认通过消息状态自动维护对话历史（短期记忆），可实现基础的多轮对话上下文关联。对于复杂场景，还可通过自定义状态schema，让Agent记忆对话历史之外的额外信息（如用户偏好、任务配置），实现高级记忆能力。

核心规则（LangChain 1.0+）

1. 自定义状态schema必须继承，且为类型；
2. 不再支持Pydantic模型和dataclasses，仅兼容TypedDict；
3. 自定义状态有两种定义方式，中间件方式为官方推荐。

方式1：通过中间件定义自定义状态（推荐）

适用场景：自定义状态需要被特定中间件/工具访问，该方式可将状态扩展与相关的中间件/工具作用域绑定，实现模块化开发。

方式2：通过state_schema参数定义（快捷方式）

适用场景：自定义状态仅在工具中使用，无需中间件处理，是快速实现自定义状态的方式。

3. 流式输出（Streaming）

方法会等待Agent完成所有步骤后返回最终结果，若Agent需要执行多轮工具调用，会出现较长的等待时间。LangChain提供方法实现流式输出，可实时捕获Agent的中间执行步骤（如模型推理、工具调用）和渐进式结果，提升用户体验。

流式输出核心示例

代码详解：

1. 返回生成器，通过for循环迭代获取流式数据；
2. 是最常用的流式模式，表示按Agent的状态值流式返回，每个chunk包含当前的完整状态；
3. 从获取最新的一条消息，区分普通文本消息和工具调用消息，分别做个性化输出；
4. 包含工具调用的详细信息（如工具名称、参数、调用ID），可实时展示Agent的行动过程。

流式输出效果：实时打印「调用搜索工具→返回搜索结果→Agent总结结果」的全过程，而非等待所有步骤完成后一次性输出。

中间件是LangChain Agent最强大的扩展机制，为Agent提供了无侵入式的行为定制能力，可在Agent执行的不同阶段拦截并修改数据流向，实现自定义逻辑，而无需改动Agent的核心代码。

中间件的核心作用

中间件可在Agent的模型调用前、工具调用前、状态处理前/后等关键节点执行自定义逻辑，典型应用场景包括：

• 实现动态模型选择、动态工具过滤、动态系统提示词；
• 自定义工具错误处理、模型响应校验（如内容风控、输出过滤）；
• 处理状态预处理（如消息裁剪、上下文注入）；
• 添加自定义日志、监控、埋点（如记录模型调用耗时、工具调用次数）；
• 实现请求/响应的格式转换。

中间件的核心特性

1. 无侵入式：无需修改Agent的核心代码，仅需通过参数挂载，符合“开闭原则”；
2. 可组合性：支持同时挂载多个中间件，按顺序执行；
3. 场景化：提供、、等专用装饰器，适配不同的扩展场景；
4. 可自定义：可继承类，实现自定义的中间件类，适配复杂的扩展需求。

中间件与Agent的融合

本文中讲解的动态模型、动态工具、动态提示词、工具错误处理等功能，均是通过中间件实现的，中间件是连接基础组件和高级特性的桥梁，也是LangChain Agent适配生产环境复杂需求的核心。

LangChain Agents是构建LLM智能应用的核心框架，其设计核心是「基础能力标准化，高级能力可扩展」：

1. 基于可快速搭建生产级Agent，模型、工具、系统提示词三大核心组件支持极简的静态配置，满足基础开发需求；
2. 基于中间件实现全维度的动态定制，覆盖模型、工具、提示词、状态等所有核心环节，适配生产环境的复杂需求；
3. ReAct循环是Agent的核心工作模式，实现自主的推理-行动-观测迭代，无需人工干预；
4. 结构化输出、记忆、流式输出三大高级特性，解决了生产环境中结果可解析、上下文记忆、实时反馈的核心痛点；
5. 底层基于LangGraph构建，兼容Graph API的所有调用方式，可无缝扩展为更复杂的图式智能体。

LangChain Agents的设计让开发者可以快速上手，同时也为生产级定制留下了充足的扩展空间，是目前最主流的LLM智能体开发框架之一。