![[最新]LangChain Agent详细介绍](images/news1.jpg)
核心组件-AgentAgent 是一个循环调用工具的模型直到给定任务完成。[!NOTE]Agent Model HarnessHarness 的作用在给定任务中在正确的时间为模型提供正确的上下文。Harness 是围绕这个循环的一切组成部分模型、它的 Prompt、它的工具以及任何用于调整其行为的中间件。create_agent方法是一个高度可配置的 Harness。最简单的情况下你可以通过以下方式创建一个# OpenAIfromlangchain.agentsimportcreate_agent agentcreate_agent(modelopenai:gpt-5.5,toolstools)#Googlefromlangchain.agentsimportcreate_agent agentcreate_agent(modelgoogle_genai:gemini-3.5-flash,toolstools)在此基础上你可以通过model、tools和system_prompt参数直接配置基础功能。对于更高级的能力可以通过 middleware 扩展 Harness。核心组件模型传入一个模型标识字符串provider:model或一个已初始化的模型实例以选择 Agent 使用的模型。有关参数、提供商配置以及动态模型选择请参阅 Models。#OpenAIfromlangchain.agentsimportcreate_agent agentcreate_agent(modelopenai:gpt-5.5,toolstools)工具要为 Agent 提供工具可以传入任意 Python 可调用对象callable、LangChain tool 或工具字典tool dict。有关工具定义、上下文访问以及动态工具选择请参阅 Tools。fromlangchain.agentsimportcreate_agentfromlangchain.toolsimporttooltooldefsearch(query:str)-str:Search for information.returnfResults for:{query}agentcreate_agent(modelopenai:gpt-5.5,tools[search])系统 Prompt用于塑造 Agent 处理任务的方式。system_prompt参数接受字符串或SystemMessage。如果需要在运行时使用动态 Prompt请使用 middleware。agentcreate_agent(modelopenai:gpt-5.5,toolstools,system_promptYou are a helpful assistant. Be concise and accurate.,)结构化输出使用response_format让 Agent 返回经过验证的 schema。有关策略和示例请参阅 Structured output。frompydanticimportBaseModelfromlangchain.agentsimportcreate_agentclassAnswer(BaseModel):summary:strconfidence:floatagentcreate_agent(modelopenai:gpt-5.5,toolstools,response_formatAnswer)resultagent.invoke({messages:[{role:user,content:Summarize AI trends}]})result[structured_response]# Answer(summary..., confidence...)调用Invocation[!TIP]使用 LangSmith 跟踪此循环中的每一步调试工具调用并评估 Agent 输出。请按照 tracing quickstart 完成配置。我们建议你同时配置 LangSmith Engine它可以监控你的 traces检测问题并提出修复方案。你可以通过消息调用 Agent。在幕后这会向 Agent 的 State 传递一个更新。所有 Agent 的 State 中都包含一个消息序列调用 Agent传入一条新消息以及一个thread_id这样 Agent 就可以持久化并恢复对话历史fromlangchain.agentsimportcreate_agentfromlangchain_core.utils.uuidimportuuid7fromlanggraph.checkpoint.memoryimportInMemorySaver agentcreate_agent(modelopenai:gpt-5.5,tools[],checkpointerInMemorySaver(),)config{configurable:{thread_id:str(uuid7())}}resultagent.invoke({messages:[{role:user,content:Whats the weather in San Francisco?}]},configconfig,)# A follow-up turn on the same conversation: reuse the same thread_id to keep historyresultagent.invoke({messages:[{role:user,content:What about tomorrow?}]},configconfig,)[!NOTE]使用thread_id持久化对话历史要求 Agent 配置一个 checkpointer。当部署在 LangSmith 上时会自动配置一个 checkpointer。在本地运行时需要显式传入一个例如create_agent(..., checkpointerInMemorySaver())。如果你还需要向工具和 middleware 传递每次运行的配置例如用户 ID、API keys 或 feature flags请将其作为 context 与 config 一起传入。使用context_schema定义该数据的结构并通过runtime.context访问它fromdataclassesimportdataclassfromlangchain.agentsimportcreate_agentfromlangchain_core.utils.uuidimportuuid7fromlanggraph.checkpoint.memoryimportInMemorySaverdataclassclassContext:user_id:stragentcreate_agent(modelopenai:gpt-5.5,tools[],context_schemaContext,checkpointerInMemorySaver(),)resultagent.invoke({messages:[{role:user,content:Whats the weather in San Francisco?}]},config{configurable:{thread_id:str(uuid7())}},contextContext(user_iduser-123),)thread_id用于限定对话范围包括消息历史、checkpoints而context用于承载每次运行时的数据这些数据会在调用时被工具和 middleware 读取。两者通常会一起传递。更多信息请参阅 tool context 和 Runtime。流式传输Streaminginvoke会在一次运行结束时返回最终响应。如果 Agent 执行多个工具调用用户通常需要在完成之前获取进度更新。使用 streaming 可以实时展示中间消息以及工具执行活动。fromlangchain.messagesimportAIMessage,HumanMessage streamagent.stream_events({messages:[{role:user,content:Search for AI news and summarize the findings}]},versionv3,)forsnapshotinstream.values:# Each snapshot contains the full state at that pointlatest_messagesnapshot[messages][-1]iflatest_message.content:ifisinstance(latest_message,HumanMessage):print(fUser:{latest_message.content})elifisinstance(latest_message,AIMessage):print(fAgent:{latest_message.content})eliflatest_message.tool_calls:print(fCalling tools:{[tc[name]fortcinlatest_message.tool_calls]})[!TIP]有关 streaming 模式、事件类型以及 UI 展示模式请参阅 Streaming。配置 Harnesscreate_agent具有高度可扩展性。middleware 是实现自定义能力的基础组件每个 middleware 负责处理一个独立关注点在 Agent 循环中的合适时机接入并且可以与其他 middleware 自由组合。根据你的使用场景选择所需的能力即可无需引入不需要的部分。常见模式已经作为一等公民first-class的 middleware 预置实现。其他任何需求都可以通过自定义 middleware 来构建。随着 Agent 承担越来越复杂的任务它们需要在几个关键领域获得支持。middleware 生态系统提供执行环境Execution environment:工具、文件系统、沙箱以及代码执行上下文管理Context management:摘要、memory、skills 以及 Prompt 缓存规划与委派Planning and delegation:Todo 列表以及用于并行、隔离工作的 subagents容错能力Fault tolerance:重试机制、fallbacks 以及调用限制安全护栏Guardrails:PII 检测以及内容控制引导控制Steering:在执行高影响操作之前通过 Human-in-the-loop 进行审批[!TIP]create_deep_agent为长时间运行的编码和研究任务预先组装了这套能力栈默认包含 filesystem、summarization、subagents 和 prompt caching。有关完整的预构建 Harness请参阅 Deep Agents。执行环境Execution environment当 Agent 不仅能够生成文本还能够执行操作时它们的价值会更加明显。执行环境为 Agent 提供了一个工作空间包括Agent 可以调用的工具用于跨多个交互轮次读取和写入文件的文件系统用于运行脚本或 shell 命令的代码执行能力。fromlangchain.agentsimportcreate_agentfromdeepagents.backendsimportStateBackendfromdeepagents.middlewareimportFilesystemMiddleware agentcreate_agent(modelopenai:gpt-5.5,tools[search],middleware[FilesystemMiddleware(backendStateBackend())],)SeeFilesystemMiddleware, Sandboxes, Interpreters.上下文管理Context management每次模型调用都有固定的上下文窗口。随着 Agent 持续运行该窗口会被不断累积的历史记录、工具结果以及中间步骤填充。摘要Summarization会在上下文溢出之前压缩历史记录memory 会在启动时加载持久化指令使知识能够跨会话延续skills 会按需提供领域知识而不是一开始就加载全部内容。fromdeepagents.backendsimportStateBackendfromdeepagents.middlewareimportFilesystemMiddleware,MemoryMiddleware,SkillsMiddleware,SummarizationMiddleware backendStateBackend()modelopenai:gpt-5.5agentcreate_agent(modelmodel,tools[search],middleware[FilesystemMiddleware(backendbackend),SummarizationMiddleware(modelmodel,backendbackend),MemoryMiddleware(backendbackend,sources[./AGENTS.md]),SkillsMiddleware(backendbackend,sources[./skills/]),],)SeeSummarizationMiddleware,MemoryMiddleware, Skills, Context engineering.规划与委派Planning and delegation复杂任务通常超出单个上下文窗口所能处理的范围。委派机制允许主 Agent 将任务拆分成多个部分并将这些部分交给各自运行在独立上下文中的 subagents 处理从而让主 Agent 专注于协调工作而不是具体执行。任务可以并行执行同时主 Agent 的上下文保持干净。fromdeepagents.backendsimportStateBackendfromdeepagents.middlewareimportFilesystemMiddlewarefromdeepagents.middleware.subagentsimportSubAgentMiddlewarefromlangchain.agentsimportcreate_agentfromlangchain.agents.middlewareimportTodoListMiddlewarefromlangchain.toolsimporttooltooldefsearch(query:str)-str:Search for a query and return a short summary.returnfSearch results for:{query}backendStateBackend()agentcreate_agent(modelopenai:gpt-5.5,tools[search],middleware[FilesystemMiddleware(backendbackend),TodoListMiddleware(),SubAgentMiddleware(backendbackend,subagents[{name:researcher,description:Searches and returns a structured summary.,system_prompt:Use the search tool to research the question and summarize key points.,tools:[search],model:anthropic:claude-sonnet-4-6,middleware:[],}],),],)See Subagents.命名你的 Agent可以选择为 Agent 指定一个标识符。当你在多 Agent 系统中将该 Agent 作为子图subgraph嵌入时这一标识符尤其有用。agentcreate_agent(modelopenai:gpt-5.5,toolstools,nameresearch_assistant)容错能力Fault tolerance生产环境中的 Agent 会遇到一些在开发阶段很少出现的故障限流、模型超时、临时性的 API 错误。容错 middleware 会在基础设施层面处理这些问题因此你的工具和业务逻辑无需在每次调用时都编写try/catch进行处理。fromlangchain.agentsimportcreate_agentfromlangchain.agents.middlewareimportModelRetryMiddleware,ToolRetryMiddlewarefromlangchain.toolsimporttooltooldefsearch(query:str)-str:Search for a query and return a short summary.returnfSearch results for:{query}agentcreate_agent(modelopenai:gpt-5.5,tools[search],middleware[ModelRetryMiddleware(max_retries3),ToolRetryMiddleware(max_retries2),],)SeeModelRetryMiddleware,ToolRetryMiddleware, Prebuilt middleware.安全护栏Guardrails有些策略无法仅通过 Prompt 实现——它们需要以确定性的方式强制执行而不受模型行为影响。Guardrails 会在数据流经 Agent 循环时进行拦截在工具结果进入模型上下文之前应用合规规则或内容策略。fromlangchain.agentsimportcreate_agentfromlangchain.agents.middlewareimportPIIMiddlewarefromlangchain.toolsimporttooltooldefsearch(query:str)-str:Search for a query and return a short summary.returnfSearch results for:{query}agentcreate_agent(modelopenai:gpt-5.5,tools[search],middleware[PIIMiddleware(email)],)SeePIIMiddleware, Prebuilt middleware.引导控制Steering完全自主并不总是合适的。Steering 允许你在特定决策节点引入人工参与——例如在执行破坏性写入、昂贵的 API 调用或任何需要人工判断的操作之前——而无需重新设计你的 Agent。Agent 会暂停并等待人工进行批准、编辑或拒绝操作随后继续执行。fromlangchain.agentsimportcreate_agentfromlangchain.agents.middlewareimportHumanInTheLoopMiddlewarefromlangchain.toolsimporttooltooldefsearch(query:str)-str:Search for a query and return a short summary.returnfSearch results for:{query}agentcreate_agent(modelopenai:gpt-5.5,tools[search],middleware[HumanInTheLoopMiddleware(interrupt_on{write_file:True})],)SeeHumanInTheLoopMiddleware, Human-in-the-loop.Middleware 资源Middleware 概览了解 middleware 栈的工作方式以及各个 hook 触发的时机。预构建 Middleware完整参考文档包含配置示例。自定义 Middleware编写你自己的 hook用于实现业务逻辑、PII 清理等更多功能。
[最新]LangChain Agent详细介绍
核心组件-AgentAgent 是一个循环调用工具的模型直到给定任务完成。[!NOTE]Agent Model HarnessHarness 的作用在给定任务中在正确的时间为模型提供正确的上下文。Harness 是围绕这个循环的一切组成部分模型、它的 Prompt、它的工具以及任何用于调整其行为的中间件。create_agent方法是一个高度可配置的 Harness。最简单的情况下你可以通过以下方式创建一个# OpenAIfromlangchain.agentsimportcreate_agent agentcreate_agent(modelopenai:gpt-5.5,toolstools)#Googlefromlangchain.agentsimportcreate_agent agentcreate_agent(modelgoogle_genai:gemini-3.5-flash,toolstools)在此基础上你可以通过model、tools和system_prompt参数直接配置基础功能。对于更高级的能力可以通过 middleware 扩展 Harness。核心组件模型传入一个模型标识字符串provider:model或一个已初始化的模型实例以选择 Agent 使用的模型。有关参数、提供商配置以及动态模型选择请参阅 Models。#OpenAIfromlangchain.agentsimportcreate_agent agentcreate_agent(modelopenai:gpt-5.5,toolstools)工具要为 Agent 提供工具可以传入任意 Python 可调用对象callable、LangChain tool 或工具字典tool dict。有关工具定义、上下文访问以及动态工具选择请参阅 Tools。fromlangchain.agentsimportcreate_agentfromlangchain.toolsimporttooltooldefsearch(query:str)-str:Search for information.returnfResults for:{query}agentcreate_agent(modelopenai:gpt-5.5,tools[search])系统 Prompt用于塑造 Agent 处理任务的方式。system_prompt参数接受字符串或SystemMessage。如果需要在运行时使用动态 Prompt请使用 middleware。agentcreate_agent(modelopenai:gpt-5.5,toolstools,system_promptYou are a helpful assistant. Be concise and accurate.,)结构化输出使用response_format让 Agent 返回经过验证的 schema。有关策略和示例请参阅 Structured output。frompydanticimportBaseModelfromlangchain.agentsimportcreate_agentclassAnswer(BaseModel):summary:strconfidence:floatagentcreate_agent(modelopenai:gpt-5.5,toolstools,response_formatAnswer)resultagent.invoke({messages:[{role:user,content:Summarize AI trends}]})result[structured_response]# Answer(summary..., confidence...)调用Invocation[!TIP]使用 LangSmith 跟踪此循环中的每一步调试工具调用并评估 Agent 输出。请按照 tracing quickstart 完成配置。我们建议你同时配置 LangSmith Engine它可以监控你的 traces检测问题并提出修复方案。你可以通过消息调用 Agent。在幕后这会向 Agent 的 State 传递一个更新。所有 Agent 的 State 中都包含一个消息序列调用 Agent传入一条新消息以及一个thread_id这样 Agent 就可以持久化并恢复对话历史fromlangchain.agentsimportcreate_agentfromlangchain_core.utils.uuidimportuuid7fromlanggraph.checkpoint.memoryimportInMemorySaver agentcreate_agent(modelopenai:gpt-5.5,tools[],checkpointerInMemorySaver(),)config{configurable:{thread_id:str(uuid7())}}resultagent.invoke({messages:[{role:user,content:Whats the weather in San Francisco?}]},configconfig,)# A follow-up turn on the same conversation: reuse the same thread_id to keep historyresultagent.invoke({messages:[{role:user,content:What about tomorrow?}]},configconfig,)[!NOTE]使用thread_id持久化对话历史要求 Agent 配置一个 checkpointer。当部署在 LangSmith 上时会自动配置一个 checkpointer。在本地运行时需要显式传入一个例如create_agent(..., checkpointerInMemorySaver())。如果你还需要向工具和 middleware 传递每次运行的配置例如用户 ID、API keys 或 feature flags请将其作为 context 与 config 一起传入。使用context_schema定义该数据的结构并通过runtime.context访问它fromdataclassesimportdataclassfromlangchain.agentsimportcreate_agentfromlangchain_core.utils.uuidimportuuid7fromlanggraph.checkpoint.memoryimportInMemorySaverdataclassclassContext:user_id:stragentcreate_agent(modelopenai:gpt-5.5,tools[],context_schemaContext,checkpointerInMemorySaver(),)resultagent.invoke({messages:[{role:user,content:Whats the weather in San Francisco?}]},config{configurable:{thread_id:str(uuid7())}},contextContext(user_iduser-123),)thread_id用于限定对话范围包括消息历史、checkpoints而context用于承载每次运行时的数据这些数据会在调用时被工具和 middleware 读取。两者通常会一起传递。更多信息请参阅 tool context 和 Runtime。流式传输Streaminginvoke会在一次运行结束时返回最终响应。如果 Agent 执行多个工具调用用户通常需要在完成之前获取进度更新。使用 streaming 可以实时展示中间消息以及工具执行活动。fromlangchain.messagesimportAIMessage,HumanMessage streamagent.stream_events({messages:[{role:user,content:Search for AI news and summarize the findings}]},versionv3,)forsnapshotinstream.values:# Each snapshot contains the full state at that pointlatest_messagesnapshot[messages][-1]iflatest_message.content:ifisinstance(latest_message,HumanMessage):print(fUser:{latest_message.content})elifisinstance(latest_message,AIMessage):print(fAgent:{latest_message.content})eliflatest_message.tool_calls:print(fCalling tools:{[tc[name]fortcinlatest_message.tool_calls]})[!TIP]有关 streaming 模式、事件类型以及 UI 展示模式请参阅 Streaming。配置 Harnesscreate_agent具有高度可扩展性。middleware 是实现自定义能力的基础组件每个 middleware 负责处理一个独立关注点在 Agent 循环中的合适时机接入并且可以与其他 middleware 自由组合。根据你的使用场景选择所需的能力即可无需引入不需要的部分。常见模式已经作为一等公民first-class的 middleware 预置实现。其他任何需求都可以通过自定义 middleware 来构建。随着 Agent 承担越来越复杂的任务它们需要在几个关键领域获得支持。middleware 生态系统提供执行环境Execution environment:工具、文件系统、沙箱以及代码执行上下文管理Context management:摘要、memory、skills 以及 Prompt 缓存规划与委派Planning and delegation:Todo 列表以及用于并行、隔离工作的 subagents容错能力Fault tolerance:重试机制、fallbacks 以及调用限制安全护栏Guardrails:PII 检测以及内容控制引导控制Steering:在执行高影响操作之前通过 Human-in-the-loop 进行审批[!TIP]create_deep_agent为长时间运行的编码和研究任务预先组装了这套能力栈默认包含 filesystem、summarization、subagents 和 prompt caching。有关完整的预构建 Harness请参阅 Deep Agents。执行环境Execution environment当 Agent 不仅能够生成文本还能够执行操作时它们的价值会更加明显。执行环境为 Agent 提供了一个工作空间包括Agent 可以调用的工具用于跨多个交互轮次读取和写入文件的文件系统用于运行脚本或 shell 命令的代码执行能力。fromlangchain.agentsimportcreate_agentfromdeepagents.backendsimportStateBackendfromdeepagents.middlewareimportFilesystemMiddleware agentcreate_agent(modelopenai:gpt-5.5,tools[search],middleware[FilesystemMiddleware(backendStateBackend())],)SeeFilesystemMiddleware, Sandboxes, Interpreters.上下文管理Context management每次模型调用都有固定的上下文窗口。随着 Agent 持续运行该窗口会被不断累积的历史记录、工具结果以及中间步骤填充。摘要Summarization会在上下文溢出之前压缩历史记录memory 会在启动时加载持久化指令使知识能够跨会话延续skills 会按需提供领域知识而不是一开始就加载全部内容。fromdeepagents.backendsimportStateBackendfromdeepagents.middlewareimportFilesystemMiddleware,MemoryMiddleware,SkillsMiddleware,SummarizationMiddleware backendStateBackend()modelopenai:gpt-5.5agentcreate_agent(modelmodel,tools[search],middleware[FilesystemMiddleware(backendbackend),SummarizationMiddleware(modelmodel,backendbackend),MemoryMiddleware(backendbackend,sources[./AGENTS.md]),SkillsMiddleware(backendbackend,sources[./skills/]),],)SeeSummarizationMiddleware,MemoryMiddleware, Skills, Context engineering.规划与委派Planning and delegation复杂任务通常超出单个上下文窗口所能处理的范围。委派机制允许主 Agent 将任务拆分成多个部分并将这些部分交给各自运行在独立上下文中的 subagents 处理从而让主 Agent 专注于协调工作而不是具体执行。任务可以并行执行同时主 Agent 的上下文保持干净。fromdeepagents.backendsimportStateBackendfromdeepagents.middlewareimportFilesystemMiddlewarefromdeepagents.middleware.subagentsimportSubAgentMiddlewarefromlangchain.agentsimportcreate_agentfromlangchain.agents.middlewareimportTodoListMiddlewarefromlangchain.toolsimporttooltooldefsearch(query:str)-str:Search for a query and return a short summary.returnfSearch results for:{query}backendStateBackend()agentcreate_agent(modelopenai:gpt-5.5,tools[search],middleware[FilesystemMiddleware(backendbackend),TodoListMiddleware(),SubAgentMiddleware(backendbackend,subagents[{name:researcher,description:Searches and returns a structured summary.,system_prompt:Use the search tool to research the question and summarize key points.,tools:[search],model:anthropic:claude-sonnet-4-6,middleware:[],}],),],)See Subagents.命名你的 Agent可以选择为 Agent 指定一个标识符。当你在多 Agent 系统中将该 Agent 作为子图subgraph嵌入时这一标识符尤其有用。agentcreate_agent(modelopenai:gpt-5.5,toolstools,nameresearch_assistant)容错能力Fault tolerance生产环境中的 Agent 会遇到一些在开发阶段很少出现的故障限流、模型超时、临时性的 API 错误。容错 middleware 会在基础设施层面处理这些问题因此你的工具和业务逻辑无需在每次调用时都编写try/catch进行处理。fromlangchain.agentsimportcreate_agentfromlangchain.agents.middlewareimportModelRetryMiddleware,ToolRetryMiddlewarefromlangchain.toolsimporttooltooldefsearch(query:str)-str:Search for a query and return a short summary.returnfSearch results for:{query}agentcreate_agent(modelopenai:gpt-5.5,tools[search],middleware[ModelRetryMiddleware(max_retries3),ToolRetryMiddleware(max_retries2),],)SeeModelRetryMiddleware,ToolRetryMiddleware, Prebuilt middleware.安全护栏Guardrails有些策略无法仅通过 Prompt 实现——它们需要以确定性的方式强制执行而不受模型行为影响。Guardrails 会在数据流经 Agent 循环时进行拦截在工具结果进入模型上下文之前应用合规规则或内容策略。fromlangchain.agentsimportcreate_agentfromlangchain.agents.middlewareimportPIIMiddlewarefromlangchain.toolsimporttooltooldefsearch(query:str)-str:Search for a query and return a short summary.returnfSearch results for:{query}agentcreate_agent(modelopenai:gpt-5.5,tools[search],middleware[PIIMiddleware(email)],)SeePIIMiddleware, Prebuilt middleware.引导控制Steering完全自主并不总是合适的。Steering 允许你在特定决策节点引入人工参与——例如在执行破坏性写入、昂贵的 API 调用或任何需要人工判断的操作之前——而无需重新设计你的 Agent。Agent 会暂停并等待人工进行批准、编辑或拒绝操作随后继续执行。fromlangchain.agentsimportcreate_agentfromlangchain.agents.middlewareimportHumanInTheLoopMiddlewarefromlangchain.toolsimporttooltooldefsearch(query:str)-str:Search for a query and return a short summary.returnfSearch results for:{query}agentcreate_agent(modelopenai:gpt-5.5,tools[search],middleware[HumanInTheLoopMiddleware(interrupt_on{write_file:True})],)SeeHumanInTheLoopMiddleware, Human-in-the-loop.Middleware 资源Middleware 概览了解 middleware 栈的工作方式以及各个 hook 触发的时机。预构建 Middleware完整参考文档包含配置示例。自定义 Middleware编写你自己的 hook用于实现业务逻辑、PII 清理等更多功能。
