create_agent

LangChain 的智能体创建函数

LangChain create_agent 完全指南：从入门到生产级智能体开发

一、create_agent 简介

create_agent 是 LangChain 1.0 中用于构建智能体的核心函数。它基于 LangGraph 在底层构建了一个图式运行时，将“模型推理 → 工具选择 → 参数绑定 → 结果处理”的完整闭环封装在一个高阶层接口中。换句话说，你不需要手动维护复杂的流程控制代码，只需声明模型、工具和系统提示词，create_agent 就会自动为你搭建一个能够在需要时自主调用工具的智能体。

与旧版 API 相比，create_agent 不仅是语法的简化，更是一次架构层面的进化——它废弃了 initialize_agent、create_react_agent 等五花八门的入口，并引入了中间件（Middleware）机制，让开发者可以在不修改核心逻辑的前提下为智能体注入重试、限流、人工审批等生产级能力。

二、核心参数详解

create_agent 的函数签名如下：

from langchain.agents import create_agent

agent = create_agent(
    model,                    # 必填：LLM 模型实例或模型标识符字符串
    tools=None,               # 可选：工具列表
    system_prompt=None,       # 可选：系统提示词
    middleware=[],            # 可选：中间件列表
    response_format=None,     # 可选：结构化输出格式
    state_schema=None,        # 可选：自定义状态 schema
    context_schema=None,      # 可选：自定义上下文 schema
    checkpointer=None,        # 可选：持久化检查点
    store=None,               # 可选：长期存储
    interrupt_before=None,    # 可选：在指定节点前中断
    interrupt_after=None,     # 可选：在指定节点后中断
    debug=False,              # 可选：开启调试模式
    name=None,                # 可选：Agent 名称
    cache=None,               # 可选：缓存实例
)

返回值：一个编译好的 CompiledStateGraph，可通过 invoke、stream、batch 等方法执行智能体。

2.1 model（必填）

# 方式一：使用模型标识符字符串（推荐入门）
agent = create_agent("gpt-4o", tools=tools)

# 方式二：直接传入 ChatModel 实例（推荐生产环境）
from langchain_openai import ChatOpenAI
model = ChatOpenAI(model="gpt-4o", temperature=0.1)
agent = create_agent(model, tools=tools)

模型标识符字符串支持自动推断供应商（如 "gpt-4o" 会被自动推断为 "openai:gpt-4o"），方便快速上手。而直接传入实例则让你可以精确控制 temperature、max_tokens、timeout 等参数。

支持的常见模型：OpenAI（gpt-4o、gpt-4-turbo）、Anthropic（claude-sonnet-4-5）、Google（gemini-1.5-pro）、通义千问（qwen-max）、DeepSeek等。

2.2 tools（可选）

from langchain_core.tools import tool

# 方式一：@tool 装饰器（最推荐）
@tool(description="查询指定城市的实时天气")
def get_weather(city: str) -> str:
    """根据城市名称查询当前天气情况。"""
    return f"{city}今日天气晴朗，25度"

# 方式二：纯 Python 函数（自动推断）
def calculate(expression: str) -> float:
    """执行数学计算。"""
    return eval(expression)

agent = create_agent("gpt-4o", tools=[get_weather, calculate, ...])

工具列表中的每个工具都会暴露给智能体，模型会根据问题内容自动判断是否需要调用以及调用哪个工具。@tool 装饰器的 description 参数尤其重要——模型正是依据这个描述来决定是否选用该工具的。

2.3 system_prompt（可选）

agent = create_agent(
    model="gpt-4o",
    tools=tools,
    system_prompt="你是一个专业的天气助手，回答关于天气的问题时要准确、简洁。若用户询问其他无关内容，请委婉拒绝。"
)

在 LangChain 1.0 中，不再需要手动构建 ChatPromptTemplate。只需传入字符串，框架会自动将其组合成完整的系统提示词，引导模型的输出方向。

2.4 middleware（可选）

中间件是 LangChain 1.0 的核心扩展机制。通过 middleware 参数，你可以方便地为 Agent 注入各种横切关注点，如重试、回退、限流、人工审批等。

from langchain.agents.middleware import (
    ModelRetryMiddleware,
    ModelCallLimitMiddleware,
    SummarizationMiddleware
)

agent = create_agent(
    model="gpt-4o",
    tools=tools,
    middleware=[
        ModelRetryMiddleware(max_retries=3, backoff_factor=2.0),  # 模型失败自动重试
        ModelCallLimitMiddleware(run_limit=10, exit_behavior="end"),  # 限制调用次数
        SummarizationMiddleware(trigger=("tokens", 4000), model="gpt-4o-mini")  # 对话总结
    ]
)

2.5 response_format（可选）

from pydantic import BaseModel, Field

class WeatherResponse(BaseModel):
    location: str = Field(description="城市名称")
    weather: str = Field(description="天气状况")
    temperature: str = Field(description="温度数值")

agent = create_agent(
    model="gpt-4o",
    tools=[get_weather],
    response_format=WeatherResponse
)

result = agent.invoke({"messages": [{"role": "user", "content": "上海天气如何？"}]})
# result 中的内容已经是一个 WeatherResponse 实例，可以直接访问属性

通过 response_format 参数，你可以强制 Agent 按照预定义的格式返回结果——无需手动解析，直接获得 Pydantic 模型实例或 JSON 对象。

2.6 checkpointer（可选）

from langgraph.checkpoint.memory import InMemorySaver

agent = create_agent(
    model="gpt-4o",
    tools=tools,
    checkpointer=InMemorySaver()  # 开启对话记忆
)

启用 checkpointer 后，Agent 能够记住之前的对话历史，支持跨轮次的上下文记忆。

2.7 debug（可选）

agent = create_agent(model="gpt-4o", tools=tools, debug=True)

开启 debug 模式后，LangGraph 会输出详细的执行流程日志，方便开发调试。

三、实用例程

例程一：单工具 Agent——查询天气

from langchain.agents import create_agent
from langchain_openai import ChatOpenAI
from langchain_core.tools import tool

@tool(description="查询指定城市的实时天气")
def get_weather(city: str) -> str:
    """获取城市的天气信息。"""
    weather_data = {
        "北京": "晴天，25度",
        "上海": "阴天，22度",
        "广州": "多云，28度"
    }
    return weather_data.get(city, f"未找到{city}的天气信息")

model = ChatOpenAI(model="gpt-4o", temperature=0.1)
agent = create_agent(
    model=model,
    tools=[get_weather],
    system_prompt="你是天气助手，准确查询天气信息。"
)

response = agent.invoke({"messages": [{"role": "user", "content": "北京天气怎么样？"}]})
print(response["messages"][-1].content)
# 预期输出：北京晴天，25度

这个最简单的例子展示了 Agent 的核心流程：用户提问 → 模型判断需要调用 get_weather → 执行工具 → 返回结果。invoke 方法接收包含 messages 键的字典，返回的消息列表中最后一条即为 Agent 的最终回复。

例程二：多工具 Agent——查询价格 + 商品介绍

当用户的问题涉及多个方面时，Agent 可以自动拆解任务并并行调用多个工具。

from langchain.agents import create_agent
from langchain_community.chat_models import ChatTongyi
from langchain_core.tools import tool

@tool(description="查询商品价格")
def get_price(name: str) -> str:
    """获取商品的价格信息。"""
    return f"{name}的价格是10元"

@tool(description="介绍商品信息")  
def get_introduction(name: str) -> str:
    """获取商品介绍信息。"""
    return f"{name}是一款时尚舒适的衬衫"

agent = create_agent(
    model=ChatTongyi(model="qwen3-max"),
    tools=[get_price, get_introduction],
    system_prompt="你是购物助手，能回复顾客关于商品的问题。"
)

# 使用 stream 实现流式输出
for chunk in agent.stream(
    {"messages": [{"role": "user", "content": "衬衫'吖丫'的价格是多少？请介绍一下这款衬衫"}]},
    stream_mode="values"
):
    latest_msg = chunk['messages'][-1]
    if hasattr(latest_msg, 'tool_calls') and latest_msg.tool_calls:
        print(f"🔧 正在调用工具: {[t['name'] for t in latest_msg.tool_calls]}")
    if latest_msg.content:
        print(latest_msg.content)

当遇到“价格”和“介绍”两个需求时，Agent 会自动同时调用 get_price 和 get_introduction 两个工具，然后将结果整合后返回。这个例子展示了 Agent 的“拆解问题 + 多工具协作”能力。

例程三：RAG Agent——自主检索文档

将检索器包装为工具后，Agent 可以自主决定何时需要检索、检索什么内容，实现 Agentic RAG。

from langchain.agents import create_agent
from langchain_openai import ChatOpenAI
from langchain_core.tools import tool
from langchain_community.vectorstores import FAISS
from langchain_openai import OpenAIEmbeddings

# 假设我们已经有一个向量数据库
embeddings = OpenAIEmbeddings()
vectorstore = FAISS.load_local("faiss_index", embeddings)
retriever = vectorstore.as_retriever(search_kwargs={"k": 3})

@tool(description="对于涉及公司内部知识库的问题，使用此工具检索相关文档")
def search_knowledge_base(query: str) -> str:
    """从企业知识库检索相关信息。"""
    docs = retriever.invoke(query)
    if not docs:
        return "未找到相关信息"
    return "\n\n".join([doc.page_content for doc in docs])

agent = create_agent(
    model=ChatOpenAI(model="gpt-4o"),
    tools=[search_knowledge_base],
    system_prompt="你是企业知识助手。当需要查询公司内部信息时，使用 search_knowledge_base 工具。"
)

response = agent.invoke({"messages": [{"role": "user", "content": "公司的报销政策是什么？"}]})

这种方式的优势在于：模型自主控制“何时搜、搜什么以及搜几次”，相比固定流程的 RAG 具有更强的适应性，能够处理多轮对话和复杂的推理需求。

例程四：结构化输出 Agent

通过 response_format 参数强制 Agent 以结构化格式返回数据。

from langchain.agents import create_agent
from langchain_openai import ChatOpenAI
from pydantic import BaseModel, Field
from langchain_core.tools import tool

class WeatherResponse(BaseModel):
    city: str = Field(description="城市名称")
    condition: str = Field(description="天气状况，如：晴、雨、多云")
    temperature: str = Field(description="温度，如：25°C")
    humidity: str = Field(description="湿度百分比，如：65%")
    advice: str = Field(description="天气相关的生活建议")

@tool(description="查询指定城市的天气信息")
def get_full_weather(city: str) -> dict:
    """获取完整天气信息。"""
    return {
        "city": city,
        "condition": "晴",
        "temperature": "25°C",
        "humidity": "65%",
        "advice": "适合户外活动，注意防晒"
    }

agent = create_agent(
    model=ChatOpenAI(model="gpt-4o"),
    tools=[get_full_weather],
    response_format=WeatherResponse  # 强制按此格式输出
)

result = agent.invoke({"messages": [{"role": "user", "content": "上海今天天气如何？"}]})
weather_data = result["messages"][-1].content  # 将自动转换为 WeatherResponse 实例
print(f"{weather_data.city}: {weather_data.condition}, {weather_data.temperature}")

结构化输出让智能体的返回结果可以直接用于下游数据处理，无需手动解析自然语言。

例程五：中间件增强 Agent——重试 + 限流 + 对话总结

from langchain.agents import create_agent
from langchain_openai import ChatOpenAI
from langchain.agents.middleware import (
    ModelRetryMiddleware,
    ModelCallLimitMiddleware,
    SummarizationMiddleware,
    ToolRetryMiddleware
)
from langchain_core.tools import tool

@tool(description="计算表达式")
def calculator(expression: str) -> float:
    """执行数学计算。"""
    return eval(expression)

agent = create_agent(
    model=ChatOpenAI(model="gpt-4o", temperature=0.1),
    tools=[calculator],
    middleware=[
        ModelRetryMiddleware(
            max_retries=3,
            backoff_factor=2.0,
            initial_delay=1.0
        ),  # 模型调用失败时自动重试
        ToolRetryMiddleware(
            max_retries=2,
            backoff_factor=2.0
        ),  # 工具执行失败时自动重试
        ModelCallLimitMiddleware(
            run_limit=10,
            exit_behavior="end"
        ),  # 单次会话最多调用10次模型
        SummarizationMiddleware(
            model="gpt-4o-mini",  # 使用更便宜的模型做总结
            trigger=[("tokens", 4000), ("messages", 6)],  # 触发条件
            keep=("messages", 20)  # 保留最近20条原始消息
        )  # 长对话自动总结
    ]
)

中间件的引入让智能体具备了生产级的可靠性，从失败重试到成本控制，从上下文管理到调用限流，都可以通过声明式配置实现。

例程六：Human-in-the-Loop Agent——人工审批敏感操作

from langchain.agents import create_agent
from langchain_openai import ChatOpenAI
from langchain.agents.middleware import HumanInTheLoopMiddleware
from langgraph.checkpoint.memory import InMemorySaver
from langchain_core.tools import tool

@tool(description="将订单状态更新为已发货")
def update_order_status(order_id: str, status: str) -> str:
    """更新订单状态（高危操作，需要人工审批）。"""
    return f"订单 {order_id} 已更新为 {status}"

@tool
def query_order_status(order_id: str) -> str:
    """查询订单状态（安全操作，不需要审批）。"""
    return f"订单 {order_id} 状态：待发货"

agent = create_agent(
    model=ChatOpenAI(model="gpt-4o"),
    tools=[update_order_status, query_order_status],
    checkpointer=InMemorySaver(),  # 必须搭配检查点才能暂停/恢复
    middleware=[
        HumanInTheLoopMiddleware(
            interrupt_on={
                "update_order_status": {
                    "allowed_decisions": ["approve", "reject"]  # 只允许批准或拒绝
                },
                "query_order_status": False  # 不需要人工介入
            }
        )
    ]
)

# Agent 执行时，遇到 update_order_status 会自动暂停，等待人工决策
response = agent.invoke(
    {"messages": [{"role": "user", "content": "请将订单 ORD-12345 状态标记为已发货"}]},
    config={"configurable": {"thread_id": "session-1"}}
)

对于修改数据库、发送真实邮件、执行支付等敏感操作，HumanInTheLoopMiddleware 可以在工具执行前暂停并等待人工审批，确保高风险操作的安全可控。

四、常见问题 FAQ

Q1: `create_agent` 和 `create_react_agent` 有什么区别？

create_agent 是 LangChain 1.0 中构建智能体的标准方式，由 langchain 包提供；create_react_agent 来自 langgraph.prebuilt 且已被弃用。官方迁移指南明确推荐：用 create_agent 替代 create_react_agent。

两者都实现了 ReAct 循环模式，但 create_agent 拥有更简洁的接口和更强大的中间件系统，支持重试、回退、限流、人工审批等生产级能力。

Q2: Agent 是如何决定调用哪个工具的？

Agent 依赖模型的能力来判断需要使用什么工具。模型的决策依据是：

用户的问题内容
每个工具的描述（@tool(description="...") 或函数 docstring）

因此，为工具编写清晰、准确的描述至关重要——它会直接影响模型对工具的选择。

Q3: 工具可以接受什么类型的参数？

工具函数通过类型注解（Type Hints）定义参数，LangChain 会自动将模型生成的参数转换为对应的 Python 类型。支持的类型包括 str、int、float、bool、list、dict 以及嵌套结构。

Q4: 如何为 Agent 添加多轮对话记忆力？

通过设置 checkpointer 参数并每次调用时传入线程 ID：

agent = create_agent(model, tools, checkpointer=InMemorySaver())
response = agent.invoke(
    {"messages": [{"role": "user", "content": "我的名字是张三"}]},
    config={"configurable": {"thread_id": "chat-session-1"}}
)

checkpointer 负责存储每个会话的状态快照，再次调用时传入相同的 thread_id 即可延续历史对话。

Q5: `agent.invoke` 和 `agent.stream` 的区别是什么？

方法	特点	适用场景
`invoke`	一次性返回完整结果	API 调用、期望完整响应的场景
`stream`	实时流式输出（类似 ChatGPT 打字效果）	聊天应用、需要实时反馈的场景

# 流式输出的同时捕获中间步骤
for chunk in agent.stream({"messages": [...]}, stream_mode="values"):
    msg = chunk["messages"][-1]
    # 可以实时查看工具调用和思考过程

Q6: 如何处理模型调用失败的情况？

使用 ModelRetryMiddleware 或 ModelFallbackMiddleware：

from langchain.agents.middleware import ModelRetryMiddleware, ModelFallbackMiddleware

model_primary = ChatOpenAI(model="gpt-4o")
model_fallback = ChatOpenAI(model="gpt-4o-mini")

agent = create_agent(
    model=model_primary,
    tools=tools,
    middleware=[
        ModelRetryMiddleware(max_retries=3),  # 失败重试
        ModelFallbackMiddleware(fallback_model=model_fallback)  # 切换备用模型
    ]
)

Q7: 如何在 Agent 中添加自定义日志？

实现自定义中间件或使用预配置的中间件：

from langchain.agents.middleware import create_middleware

logging_middleware = create_middleware(
    before_model=lambda req, handler: (print(f"调用模型: {req}"), handler(req))[1],
    after_model=lambda res, handler: (print(f"模型响应: {res}"), handler(res))[1],
)

agent = create_agent(model, tools, middleware=[logging_middleware])

Q8: `agent.invoke` 的输入格式是怎样的？

输入必须是一个包含 "messages" 键的字典：

result = agent.invoke({
    "messages": [
        {"role": "system", "content": "你是一个专业助手"},
        {"role": "user", "content": "北京天气如何？"}
    ]
})

支持的消息角色包括 system、user、assistant、tool 等。

Q9: 如何获取 Agent 调用了哪些工具（调试用）？

流式处理时检查消息对象中的 tool_calls 属性：

for chunk in agent.stream({...}, stream_mode="values"):
    msgs = chunk["messages"]
    if msgs and hasattr(msgs[-1], "tool_calls") and msgs[-1].tool_calls:
        tools_used = [tc["name"] for tc in msgs[-1].tool_calls]
        print(f"模型调用了: {tools_used}")

Q10: Agent 会无限循环调用工具吗？

不会。Agent 会在以下条件下停止：

模型输出的最终结果中不包含工具调用
达到了工具调用次数上限（可通过 ModelCallLimitMiddleware 或 ToolCallLimitMiddleware 设置）
触发了开发者定义的插断条件

为了确保安全，建议在生产环境中配置调用限流中间件。

Q11: `create_agent` 返回的是什么？内部是如何执行的？

create_agent 返回一个 CompiledStateGraph。这是一个被编译过的 LangGraph 状态图，包含了“模型推理 → 选择工具 → 执行工具 → 返回结果”的完整执行闭环。调用 invoke 时，Agent 在这个图结构中移动并逐步完成任务。

Q12: 为什么模型不调用我定义的“简单”函数？

可能原因：

函数的 description 不够清晰或与用户问题不匹配——模型通过描述判断何时调用，务必准确详尽地描述工具用途
模型本身不支持函数调用——确保使用的模型支持 Tool Calling 能力（大多数主流商用模型都支持）
系统提示词中隐含了“不使用工具”的指令——检查 system_prompt 是否与工具使用存在冲突

五、总结与学习建议

create_agent 是 LangChain 1.0 中构建智能体的标准入口。核心流程非常简单：定义模型 → 提供工具 → 注入中间件 → 开始调用。

但这四个步骤背后蕴含着一个极其强大的、基于图的状态管理引擎。建议你按以下路径展开学习：

从最简单的单工具智能体开始，理解“模型思考 → 调用工具 → 返回结果”的基础流程
尝试定义多个工具，让模型学习自动拆解复杂问题并并发调用
逐步引入中间件系统，为智能体添加重试、限流、管控和加固能力
结合 LangGraph 与 StateGraph 进行深度的流程定制，构建真正复杂的多节点智能体工作流

当 LLM 从纯粹的文字生成器进化为能够理解目标、调用工具并与外部世界交互的行为者时，智能体技术才真正进入了“可用”的核心阶段——而这正是 create_agent 带你抵达的地方。希望本教程能帮助你在智能体开发的旅程中少走弯路，将 AI 的能力快速落地到真实的业务场景中。

旺道跨平台系统

专业铸造企业商业门户

为私域流量与商业增长提供商弈利器

商城系统

分销系统

CRM系统

智慧门店

供应链系统

订货系统
旺道商弈网课系统

超低成本扩张，赚复利的钱

在线教学+督学+裂变+社交+促销+分销于一体的网校系统，
AI应用软件开发服务

始于需求，终于品质

定制企业级AI小程序、APP与智能系统

量身订做

跨平台

独立部署

专业打造

1321519121813027920428

LangChain create_agent 完全指南：从入门到生产级智能体开发

一、create_agent 简介

二、核心参数详解

2.1 model（必填）

2.2 tools（可选）

2.3 system_prompt（可选）

2.4 middleware（可选）

2.5 response_format（可选）

2.6 checkpointer（可选）

2.7 debug（可选）

三、实用例程

例程一：单工具 Agent——查询天气

例程二：多工具 Agent——查询价格 + 商品介绍

例程三：RAG Agent——自主检索文档

例程四：结构化输出 Agent

例程五：中间件增强 Agent——重试 + 限流 + 对话总结

例程六：Human-in-the-Loop Agent——人工审批敏感操作

四、常见问题 FAQ

Q1: create_agent 和 create_react_agent 有什么区别？

Q2: Agent 是如何决定调用哪个工具的？

Q3: 工具可以接受什么类型的参数？

Q4: 如何为 Agent 添加多轮对话记忆力？

Q5: agent.invoke 和 agent.stream 的区别是什么？

Q6: 如何处理模型调用失败的情况？

Q7: 如何在 Agent 中添加自定义日志？

Q8: agent.invoke 的输入格式是怎样的？

Q9: 如何获取 Agent 调用了哪些工具（调试用）？

Q10: Agent 会无限循环调用工具吗？

Q11: create_agent 返回的是什么？内部是如何执行的？

Q12: 为什么模型不调用我定义的“简单”函数？

五、总结与学习建议

旺道跨平台系统

专业铸造企业商业门户

为私域流量与商业增长提供商弈利器

旺道商弈网课系统

超低成本扩张，赚复利的钱

AI应用软件开发服务

始于需求，终于品质

定制企业级AI小程序、APP与智能系统

量身订做

跨平台

独立部署

专业打造

13215191218
13027920428

Q1: `create_agent` 和 `create_react_agent` 有什么区别？

Q5: `agent.invoke` 和 `agent.stream` 的区别是什么？

Q8: `agent.invoke` 的输入格式是怎样的？

Q11: `create_agent` 返回的是什么？内部是如何执行的？