LangChain
17 · Agent
create_agent、@tool、路由式多 agent
- LangChain
- Python
本节速览
这一节的每一块内容,分别是干什么的:
| 内容 | 是干什么的 |
|---|---|
| Agent 与 chain 的区别 | 谁决定流程:代码写死 vs 模型自主决定 |
| RunnableBranch | 确定性路由,按分类结果分流到固定链 |
| create_agent + @tool | 工程主线:模型自主决定调哪个工具、循环到出结果 |
| return_direct 与路由式多 agent | 工具结果直接返回;一个分诊 agent 调度多个专职 agent |
| 引导式参数收集 | 用多轮对话替代表单收集参数 |
| recursion_limit | 限制循环轮数,防止 token 失控 |
Agent 把 LLM 当作推理引擎:模型根据任务与工具集自主决策,循环执行「思考 → 选工具 → 传参调用 → 观察结果 → 决策下一步」,直到认为问题已解决。1.x 的主 API 是 create_agent(langchain 包,构建在 LangGraph 之上),0.1.x 的 AgentExecutor 体系已移除。
Agent 与 chain 的区别
没有它会怎样——固定链把流程写死:数学题一律「先检索再计算」,遇到「2+3 等于几」也跑一趟向量库;换个问法多写一条链,分支越写越多。
有了它——agent 把「下一步干什么」交给模型:该查查、该算算、够了就答,一套代码吃下多种问法。
chain 的执行流程由代码写死(确定性);agent 的流程由 LLM 在运行时决定(自主性)。判断标准:任务可以被预先枚举和拆解时,用确定性路由;必须由模型临场推理决定步骤时,才用 agent。
agent 的三大代价:安全(模型可能构造危险操作)、成本(多轮调用 token 失控)、延迟(串行 LLM 调用累加)。
两个任务对照,判断该用哪个:
任务 A:「把用户提问分成科普、编程、一般三类,各类用固定模板回答」
分类可枚举、流程固定 → RunnableBranch 路由(见下节)
任务 B:「查一下这本书里关于量子玫瑰的情节,再算 17 美元折合多少人民币」
先检索还是先计算、要不要中途补一次搜索,由问题临场决定 → create_agent
任务 A 用 agent 是浪费:多花 token、多等几秒,结果和写死的路由一样。任务 B 用路由写不出来:分支组合太多,没法预先枚举。
确定性路由:RunnableBranch
没有它会怎样——按分类走不同链,写一串 if topic == "科普": chain_a.invoke(...) elif ...,分支一多嵌套成山,加一类改三处。
有了它——(条件函数, 链) 的声明式列表,加分支加一行,顺序即优先级。
一个入口接收多领域提问、分发到各自专业 chain 的场景,不需要 agent。入口分类用 with_structured_output:
from typing import Literal # 枚举类型注解
from pydantic import BaseModel, Field # 数据模型与字段描述
from langchain_core.output_parsers import StrOutputParser # 提取纯文本
from langchain_core.prompts import ChatPromptTemplate # 带角色的消息模板
from langchain_core.runnables import RunnableBranch, RunnableMap, RunnableSequence # 路由、并行、串联
import os # 读取环境变量
from dotenv import load_dotenv # 从 .env 读环境变量
from langchain_openai import ChatOpenAI # OpenAI 聊天模型
load_dotenv()
model = ChatOpenAI(
base_url=os.environ["GLM_BASE_URL"],
api_key=os.environ["GLM_API_KEY"],
model=os.environ["GLM_MODEL_ID"],
)
def qa_chain(system: str):
"""同一模板按 system 文案生成各自领域的问答链"""
return ChatPromptTemplate.from_messages([
{"role": "system", "content": system},
{"role": "human", "content": "{input}"},
]).pipe(model).pipe(StrOutputParser())
general_chain = qa_chain("你是通用问答助手,回答简洁准确。")
science_chain = qa_chain("你是科普问答助手,回答通俗易懂,多用类比。")
programming_chain = qa_chain("你是编程助教,回答带可运行的示例代码。")
class ClassifyResult(BaseModel):
"""用户提问的分类结果"""
type: Literal["科普", "编程", "一般问题"] = Field(description="用户提问的分类")
classify_chain = RunnableSequence(
ChatPromptTemplate.from_messages([
{"role": "system", "content": '仔细思考,对用户的问题进行分类,无法分类时归入 "一般问题"'},
{"role": "human", "content": "{input}"},
]),
model.with_structured_output(ClassifyResult),
)
def classify(question): # 代码层兜底:解析失败落默认分类
try:
return classify_chain.invoke({"input": question}).type
except Exception:
return "一般问题"
branch = RunnableBranch(
(lambda x: "科普" in x["type"], science_chain),
(lambda x: "编程" in x["type"], programming_chain),
general_chain, # 无条件的最后一项是默认分支
)
final_chain = RunnableSequence(
RunnableMap(type=lambda x: classify(x["input"]), input=lambda x: x["input"]),
branch,
)
RunnableBranch 按位置接收一组 (条件函数, Runnable) 元组:条件返回 True 时执行该项 Runnable,多个条件为真只取第一个。鲁棒性来自三层:schema 层 Literal 枚举、prompt 层给「无法分类」的出口、代码层捕获异常返回默认值。该方案稳定、可控、易优化,代价是失去 agent 的自主性。
create_agent + @tool:工程主线
没有它会怎样——手写 agent 循环:调模型 → 解析 tool_calls → 执行 → 结果拼回 messages → 再调模型……几十行样板,消息格式错一点整循环崩,异常处理写到手软。
有了它——create_agent(model, tools) 一行,循环、回传、终止判断框架全包,你只管定义工具和接结果。
create_agent 接收模型、工具与系统提示,内部自动完成「调模型 → 执行 tool_calls → 结果回传 → 再调模型」的循环:
from langchain_openai import ChatOpenAI # OpenAI 聊天模型
import os # 读取环境变量
import re # 正则校验表达式
from typing import Annotated # 给参数加描述的注解
from dotenv import load_dotenv # 从 .env 读环境变量
from langchain.agents import create_agent # 创建 agent
from langchain.tools import tool # 工具定义装饰器
load_dotenv()
llm = ChatOpenAI(
base_url=os.environ["GLM_BASE_URL"],
api_key=os.environ["GLM_API_KEY"],
model=os.environ["GLM_MODEL_ID"],
)
@tool
def get_exchange_rate(
base: Annotated[str, "基准货币代码,如 USD"],
target: Annotated[str, "目标货币代码,如 CNY"],
) -> str:
"""查询两种货币之间的当前汇率"""
table = {"USD:CNY": 7.24, "USD:EUR": 0.92} # mock 数据,真实场景换汇率 API
rate = table.get(f"{base}:{target}")
return f"1 {base} = {rate} {target}" if rate else f"没有 {base} 到 {target} 的数据"
@tool
def calculator(expression: Annotated[str, "要计算的四则运算表达式"]) -> str:
"""计算四则运算表达式,如 17 * 7.24"""
if not re.fullmatch(r"[0-9+\-*/().\s]+", expression):
return "只支持数字与四则运算符的表达式"
return str(eval(expression)) # 输入已被正则限定,可安全求值
agent = create_agent(
llm, # 字符串初始化符,也可传模型实例
system_prompt="你是一个乐于助人的助手",
tools=[get_exchange_rate, calculator],
)
result = agent.invoke({
"messages": [{"role": "user", "content": "我有 17 美元,现在相当于多少人民币?"}],
})
print(result["messages"][-1].content)
# 17 美元约等于 123.08 元人民币。
工具规范:
@tool装饰器下,函数名即工具名(snake_case),docstring 即 description,类型注解即 schema,字段描述用Annotated[类型, "描述"]。- docstring 是模型判断「是否调用、何时调用」的唯一信息来源,必须写清效果。
- 执行函数内不要抛异常,把错误信息作为字符串返回,模型能据此调整下一步。
- 工具越多,描述与 schema 占的上下文越多。按需设计,不是越多越好。
- 参数先过 pydantic 校验,校验失败的错误信息直接回传给 LLM 修正重试。
多轮记忆加 checkpointer 即得(见记忆系统),一行配置:
from langchain_openai import ChatOpenAI # OpenAI 聊天模型
import os # 读取环境变量
from dotenv import load_dotenv # 从 .env 读环境变量
import re # 校验表达式
from typing import Annotated # 参数级注解
from langchain.agents import create_agent # 创建 agent
from langchain.tools import tool # 工具定义装饰器
from langgraph.checkpoint.memory import InMemorySaver # 内存版记忆持久化
load_dotenv()
llm = ChatOpenAI(
base_url=os.environ["GLM_BASE_URL"],
api_key=os.environ["GLM_API_KEY"],
model=os.environ["GLM_MODEL_ID"],
)
@tool
def get_exchange_rate(
from_currency: Annotated[str, "源货币代码,如 USD"],
to_currency: Annotated[str, "目标货币代码,如 CNY"],
) -> str:
"""查询两种货币之间的汇率"""
return "7.24"
@tool
def calculator(expression: Annotated[str, "要计算的四则运算表达式"]) -> str:
"""计算四则运算表达式,如 17 * 7.24"""
if not re.fullmatch(r"[0-9+\-*/().\s]+", expression):
return "只支持数字与四则运算符的表达式"
return str(eval(expression))
agent = create_agent(
llm,
tools=[get_exchange_rate, calculator],
checkpointer=InMemorySaver(),
)
任何 Runnable 或 chain 也能包进 tool。RAG 的检索封装成工具交给 agent 按需检索的完整做法,见部署。
return_direct 与路由式多 agent
没有它会怎样——分诊 agent 把专职 agent 的结果又拿去「总结」一遍:多一轮模型调用,又慢又花钱,总结还可能加戏改变原意。
有了它——return_direct=True 让工具结果直接作为最终答案;一层分诊调度多个专职 agent,各答各的,不过二手转述。
@tool(return_direct=True) 让工具结果直接作为 agent 最终输出,跳过「把结果再交给 LLM 总结」这一步:
from typing import Annotated # 参数级注解
from langchain.tools import tool # 工具定义装饰器
@tool(return_direct=True) # 工具结果直接返回,短路 agent 循环
def retrieve_docs(query: Annotated[str, "信息完整的独立问题"]) -> str:
"""获取知识库相关问题的答案,命中即直接返回"""
...
典型用法是路由式多 agent:入口 agent 持有多个 return_direct=True 的工具,每个工具内部是一个垂直领域的专业 agent 或 RAG chain。入口只做分类分发,命中工具即返回,省一次入口层的 LLM 调用。需要综合多个子结果再作答时不用 return_direct,让工具结果回到入口模型上下文里汇总。
引导式参数收集:多轮对话替代表单
没有它会怎样——表单一次收全参数,缺一项报错让用户重来;用户不知道 callbackUrl 是什么,填错提交、后端打回,来回三轮。
有了它——模型多轮对话缺啥问啥,还能解释参数含义、给默认值,收齐自动执行。
「从用户处收集若干结构化参数再执行动作」的场景(咨询、下单、问卷),用工具的 schema 当表单字段定义:
from langchain_openai import ChatOpenAI # OpenAI 聊天模型
import os # 读取环境变量
from dotenv import load_dotenv # 从 .env 读环境变量
from typing import Annotated, Literal # 参数级注解、枚举类型
from langchain.agents import create_agent # 创建 agent
from langchain.tools import tool # 工具定义装饰器
from langchain_core.output_parsers import StrOutputParser # 提取纯文本
from langchain_core.prompts import ChatPromptTemplate # 带角色的消息模板
from langgraph.checkpoint.memory import InMemorySaver # 内存版记忆持久化
load_dotenv()
llm = ChatOpenAI(
base_url=os.environ["GLM_BASE_URL"],
api_key=os.environ["GLM_API_KEY"],
model=os.environ["GLM_MODEL_ID"],
)
mbti_list = ["INTJ", "INTP", "ENTJ", "ENTP", "INFJ", "INFP", "ENFJ", "ENFP",
"ISTJ", "ISFJ", "ESTJ", "ESFJ", "ISTP", "ISFP", "ESTP", "ESFP"]
MbtiType = Literal[*mbti_list] # 枚举锁死取值,Python 3.11+
# 每种类型的固定描述由代码注入,不让 LLM 生成(实际项目存完整人格描述文本)
mbti_info = {t: f"{t} 型人格的典型特点说明" for t in mbti_list}
mbti_chain = ChatPromptTemplate.from_messages([
{"role": "human", "content": "以 {info} 的口吻回答:{question}"},
]).pipe(llm).pipe(StrOutputParser())
@tool
def get_mbti_chat(
type: Annotated[MbtiType, "用户的 MBTI 类型"],
question: Annotated[str, "用户的问题"],
) -> str:
"""根据用户的问题和 MBTI 类型,回答用户的问题"""
info = mbti_info[type] # 固定描述由代码注入,不让 LLM 生成
return mbti_chain.invoke({"type": type, "question": question, "info": info})
agent = create_agent(
llm,
system_prompt=(
"你是一个接待用户的助手,通过自然语言询问用户的 MBTI 类型和问题,"
"直到信息足够调用 get_mbti_chat 回答用户的问题。"
),
tools=[get_mbti_chat],
checkpointer=InMemorySaver(),
)
机制:
- 追问的分支完全由 LLM 根据对话生成,没有一行预编流程代码。参数收集齐的判定标准就是 schema:模型认为能构造出满足 schema 的参数时才发起调用。
Literal枚举把取值锁死在合法集合内,模型编造的非法值过不了 pydantic 校验。- 固定答案的数据(性格描述、卦辞等)外置到 JSON 文件,代码读取后注入。LLM 负责理解与措辞,固定事实由代码提供。
- system prompt 里显式点名工具名(「直到信息足够调用 get_mbti_chat」)能提高收集到位后的调用率。
recursion_limit:防止 token 失控
没有它会怎样——工具有 bug 一直返回异常,模型锲而不舍地重试,循环几十轮:token 烧爆、接口超时,日志里全是同一轮的重复调用。
有了它——recursion_limit 钉住最大轮数,超限抛错熔断,损失可控。
agent 的工具循环没有天然上限,模型死循环时 token 消耗无界。recursion_limit 限制底层 LangGraph 图的最大超步数(一轮「模型 → 工具」循环约两步),默认 25,超限抛 GraphRecursionError:
import os # 读取环境变量
from dotenv import load_dotenv # 从 .env 读环境变量
from langchain.agents import create_agent # 创建 agent
from langchain.tools import tool # 工具定义装饰器
from langchain_openai import ChatOpenAI # OpenAI 聊天模型
from langgraph.errors import GraphRecursionError # 步数超限异常
load_dotenv()
@tool
def flaky_task(x: str) -> str:
"""演示用:一个始终失败的工具"""
raise RuntimeError("boom")
agent = create_agent(
ChatOpenAI(
base_url=os.environ["GLM_BASE_URL"],
api_key=os.environ["GLM_API_KEY"],
model=os.environ["GLM_MODEL_ID"],
),
tools=[flaky_task],
)
try:
result = agent.invoke(
{"messages": [{"role": "user", "content": "..."}]},
{"recursion_limit": 15}, # 与 configurable 平级,不要塞进 configurable
)
except GraphRecursionError:
result = "抱歉,这次任务没有在限定步数内完成,请换个问法或稍后再试。"
配合 LangSmith(见配置)可视化追踪每一轮的思考与工具调用,排查死循环比翻日志高效。
0.x 迁移对照
| 0.1.x(已废弃) | 1.x 写法 |
|---|---|
create_react_agent / AgentExecutor(agent=..., tools=...) | create_agent(model=..., tools=..., system_prompt=...) |
| hub 拉 prompt + 双 placeholder | system_prompt 参数,历史由线程 messages 统一承载 |
DynamicTool / DynamicStructuredTool | @tool 装饰器 |
RunnableWithMessageHistory 包装 | checkpointer + thread_id |
max_iterations | recursion_limit |
选型结论:任务可预先描述、相对确定,用 RunnableBranch 路由;确需 agent,用 create_agent + @tool,配 recursion_limit 与 SummarizationMiddleware。
上一节:LangGraph 基础 · 下一节:流式 API 与部署