LangChain / Core components / Agents
原文链接：https://docs.langchain.com/oss/python/langchain/agents
文中的代码只添加了Google的示例，如果想用其他的类型，请看原文
核心组件
智能体
智能体是一个循环调用工具直到完成给定任务的模型。
核心智能体循环示意图
智能体 = 模型 + 工具集（Harness）
工具集（Harness）的工作：在正确的时间为给定任务向模型提供正确的上下文。
工具集是围绕该循环的一切：模型、其提示词、其工具，以及任何塑造其行为的中间件。
create_agent是一个高度可配置的工具集。最简单的情况下，你可以这样创建一个：
fromlangchain.agentsimportcreate_agent agent=create_agent(model="google_genai:gemini-3.5-flash",tools=tools)在此基础上，你可以直接使用model=、tools=和system_prompt=参数配置基本功能。如需更高级的功能，可通过中间件扩展工具集。
核心组件
智能体模型和工具集组件示意图
模型
传入模型标识符字符串（"provider:model"）或已初始化的模型实例来选择智能体的模型。有关参数、提供商设置和动态模型选择，请参阅模型。
fromlangchain.agentsimportcreate_agent agent=create_agent(model="google_genai:gemini-3.5-flash",tools=tools)工具
要为智能体提供工具，可以传入任何 Python 可调用对象、LangChain 工具或工具字典。有关工具定义、上下文访问和动态工具选择，请参阅工具。
fromlangchain.agentsimportcreate_agentfromlangchain.toolsimporttool@tooldefsearch(query:str)->str:"""搜索信息。"""returnf"查询结果：{query}"agent=create_agent(model="google_genai:gemini-3.5-flash",tools=[search])系统提示词
塑造智能体处理任务的方式。系统提示词参数接受字符串或SystemMessage。如需在运行时使用动态提示词，请使用中间件。
agent=create_agent(model="google_genai:gemini-3.5-flash",tools=tools,system_prompt="你是一个有用的助手。请保持简洁和准确。",)结构化输出
使用response_format=从智能体返回经过验证的模式。有关策略和示例，请参阅结构化输出。
frompydanticimportBaseModelfromlangchain.agentsimportcreate_agentclassAnswer(BaseModel):summary:strconfidence:floatagent=create_agent(model="google_genai:gemini-3.5-flash",tools=tools,response_format=Answer)result=agent.invoke({"messages":[{"role":"user","content":"总结AI趋势"}]})result["structured_response"]# Answer(summary=..., confidence=...)调用
使用 LangSmith 跟踪此循环的每一步、调试工具调用并评估智能体输出。请按照跟踪快速入门进行设置。我们还建议您设置 LangSmith Engine，它会监控您的跟踪、检测问题并提出修复建议。
您可以使用消息调用智能体。在后台，这会向智能体的状态传递更新。所有智能体在其状态中都包含一系列消息；要调用智能体，请传递一条新消息以及一个thread_id，以便智能体可以持久化并恢复对话历史：
fromlangchain.agentsimportcreate_agentfromlangchain_core.utils.uuidimportuuid7fromlanggraph.checkpoint.memoryimportInMemorySaver agent=create_agent(model="google_genai:gemini-3.5-flash",tools=[],checkpointer=InMemorySaver(),)config={"configurable":{"thread_id":str(uuid7())}}result=agent.invoke({"messages":[{"role":"user","content":"旧金山的天气怎么样？"}]},config=config,)# 同一对话的后续轮次：重用相同的 thread_id 以保留历史result=agent.invoke({"messages":[{"role":"user","content":"那明天呢？"}]},config=config,)使用thread_id持久化对话历史需要为智能体配置检查点。部署在 LangSmith 上时，检查点会自动配置。在本地，请显式传入一个，例如create_agent(..., checkpointer=InMemorySaver())。
如果您还需要将每次运行的配置（如用户 ID、API 密钥或功能标志）传递给工具和中间件，请将其作为context与config一起传递。使用context_schema定义该数据的形状，并通过runtime.context访问它：
fromdataclassesimportdataclassfromlangchain.agentsimportcreate_agentfromlangchain_core.utils.uuidimportuuid7fromlanggraph.checkpoint.memoryimportInMemorySaver@dataclassclassContext:user_id:stragent=create_agent(model="google_genai:gemini-3.5-flash",tools=[],context_schema=Context,checkpointer=InMemorySaver(),)result=agent.invoke({"messages":[{"role":"user","content":"旧金山的天气怎么样？"}]},config={"configurable":{"thread_id":str(uuid7())}},context=Context(user_id="user-123"),)thread_id限定对话范围（消息历史、检查点），而context携带工具和中间件在调用时读取的每次运行数据。两者通常一起传递。请参阅工具上下文和运行时。
流式传输
invoke在运行结束时返回最终响应。如果智能体执行多次工具调用，用户通常需要在完成之前获得进度更新。使用流式传输可在中间消息和工具活动发生时实时呈现它们。
fromlangchain.messagesimportAIMessage,HumanMessage stream=agent.stream_events({"messages":[{"role":"user","content":"搜索AI新闻并总结发现"}]},version="v3",)forsnapshotinstream.values:# 每个快照包含该时间点的完整状态latest_message=snapshot["messages"][-1]iflatest_message.content:ifisinstance(latest_message,HumanMessage):print(f"用户：{latest_message.content}")elifisinstance(latest_message,AIMessage):print(f"智能体：{latest_message.content}")eliflatest_message.tool_calls:print(f"正在调用工具：{[tc['name']fortcinlatest_message.tool_calls]}")有关流式模式、事件类型和 UI 模式，请参阅流式传输。
配置工具集
create_agent具有高度可扩展性。中间件是定制的原语：每个组件处理一个关注点，在正确的时机挂接到智能体循环中，并可以自由地与任何其他组件组合。只取用例所需的部分，跳过其余部分。
常见模式已作为一级中间件预置。您可以将任何其他内容构建为自定义中间件。
按类别划分的智能体工具集功能
当智能体承担复杂工作时，它们需要在几个关键领域获得支持。中间件生态系统提供：
执行环境
工具、文件系统、沙箱和代码执行
上下文管理
摘要、内存、技能和提示缓存
规划与委托
待办事项列表和用于并行、隔离工作的子智能体
容错
重试、回退和调用限制
防护栏
PII 检测和内容控制
引导
在高影响操作前进行人机协同审批
create_deep_agent为长期运行的编码和研究任务预组装了此堆栈（默认包含文件系统、摘要、子智能体和提示缓存）。有关完整的预置工具集，请参阅深度智能体。
执行环境
当智能体能够采取行动而不仅仅是生成文本时，它们尤其有用。执行环境为智能体提供了一个工作空间：可调用的工具、用于跨轮次读写文件的文件系统，以及用于运行脚本或 shell 命令的代码执行环境。
fromlangchain.agentsimportcreate_agentfromdeepagents.backendsimportStateBackendfromdeepagents.middlewareimportFilesystemMiddleware agent=create_agent(model="google_genai:gemini-3.5-flash",tools=[search],middleware=[FilesystemMiddleware(backend=StateBackend())],)请参阅 FilesystemMiddleware、沙箱、解释器。
上下文管理
每次模型调用都有固定的上下文窗口。随着智能体运行，该窗口会被累积的历史记录、工具结果和中间步骤填满。摘要可在溢出发生前压缩历史；内存可在启动时加载持久化指令，使知识跨会话延续；技能可按需提供领域知识，而无需预先加载所有内容。
fromdeepagents.backendsimportStateBackendfromdeepagents.middlewareimportFilesystemMiddleware,MemoryMiddleware,SkillsMiddleware,SummarizationMiddleware backend=StateBackend()model="google_genai:gemini-3.5-flash"agent=create_agent(model=model,tools=[search],middleware=[FilesystemMiddleware(backend=backend),SummarizationMiddleware(model=model,backend=backend),MemoryMiddleware(backend=backend,sources=["./AGENTS.md"]),SkillsMiddleware(backend=backend,sources=["./skills/"]),],)请参阅 SummarizationMiddleware、MemoryMiddleware、技能、上下文工程。
规划与委托
复杂任务通常超出单个上下文窗口的处理能力。委托让主智能体将工作分解为多个部分，将它们交给各自在独立上下文中运行的子智能体，并专注于协调而非执行。工作可以并行运行；主智能体的上下文保持整洁。
fromdeepagents.backendsimportStateBackendfromdeepagents.middlewareimportFilesystemMiddlewarefromdeepagents.middleware.subagentsimportSubAgentMiddlewarefromlangchain.agentsimportcreate_agentfromlangchain.agents.middlewareimportTodoListMiddlewarefromlangchain.toolsimporttool@tooldefsearch(query:str)->str:"""搜索查询并返回简短摘要。"""returnf"查询的搜索结果：{query}"backend=StateBackend()agent=create_agent(model="google_genai:gemini-3.5-flash",tools=[search],middleware=[FilesystemMiddleware(backend=backend),TodoListMiddleware(),SubAgentMiddleware(backend=backend,subagents=[{"name":"研究员","description":"搜索并返回结构化摘要。","system_prompt":"使用搜索工具研究问题并总结关键点。","tools":[search],"model":"anthropic:claude-sonnet-4-6","middleware":[],}],),],)为智能体命名
可选择为智能体使用标识符。当将智能体作为子图嵌入多智能体系统时，这尤其有用。
agent=create_agent(model="google_genai:gemini-3.5-flash",tools=tools,name="research_assistant")容错
生产环境中的智能体会遇到在开发中很少出现的故障：速率限制、模型超时、瞬态 API 错误。容错中间件在基础设施层面处理这些问题，因此您的工具和业务逻辑无需在每个调用周围都加上 try/catch。
fromlangchain.agentsimportcreate_agentfromlangchain.agents.middlewareimportModelRetryMiddleware,ToolRetryMiddlewarefromlangchain.toolsimporttool@tooldefsearch(query:str)->str:"""搜索查询并返回简短摘要。"""returnf"查询的搜索结果：{query}"agent=create_agent(model="google_genai:gemini-3.5-flash",tools=[search],middleware=[ModelRetryMiddleware(max_retries=3),ToolRetryMiddleware(max_retries=2),],)请参阅 ModelRetryMiddleware、ToolRetryMiddleware、预置中间件。
防护栏
有些策略无法仅通过提示词实现——无论模型做什么，它们都需要被确定性地强制执行。防护栏在数据流经智能体循环时进行拦截，在工具结果到达模型上下文之前应用合规规则或内容策略。
fromlangchain.agentsimportcreate_agentfromlangchain.agents.middlewareimportPIIMiddlewarefromlangchain.toolsimporttool@tooldefsearch(query:str)->str:"""搜索查询并返回简短摘要。"""returnf"查询的搜索结果：{query}"agent=create_agent(model="google_genai:gemini-3.5-flash",tools=[search],middleware=[PIIMiddleware("email")],)请参阅 PIIMiddleware、预置中间件。
引导
完全的自主权并不总是合适的。引导让您可以在特定的决策点引入人工干预——在破坏性写入、昂贵的 API 调用或任何需要判断的操作之前——而无需重构您的智能体。智能体会暂停并等待；人工批准、编辑或拒绝；执行继续。
fromlangchain.agentsimportcreate_agentfromlangchain.agents.middlewareimportHumanInTheLoopMiddlewarefromlangchain.toolsimporttool@tooldefsearch(query:str)->str:"""搜索查询并返回简短摘要。"""returnf"查询的搜索结果：{query}"agent=create_agent(model="google_genai:gemini-3.5-flash",tools=[search],middleware=[HumanInTheLoopMiddleware(interrupt_on={"write_file":True})],)请参阅 HumanInTheLoopMiddleware、人机协同。