一、为什么我要手写一个Agent,而不是直接用AutoGPT
先说结论:AutoGPT那套"自主目标分解"在Demo里很惊艳,但落到生产环境,问题很集中——它的规划循环不透明、token消耗不可控、工具失败后容易陷入重复调用。我上一个项目用AutoGPT风格的框架跑数据采集Agent,一个"整理竞品价格"的任务烧了12万token还没收敛,最后发现是它把"打开网页失败"当成了"需要再打开一次"。
LangChain 0.2.x的AgentExecutor给了我们一个更可控的骨架:它把"LLM决策 → 工具执行 → 观察结果回填 → 再决策"这个循环显式暴露出来,循环上限、异常处理、记忆管理都能自己插手。所以这篇文章我不讲怎么调包,而是把这个循环拆开,用约300行代码手写一遍。你会看到四个核心模块的真实实现:工具定义、记忆管理、错误处理、循环控制。
环境版本先交代清楚,避免你复现时踩版本坑:
- Python 3.11.7
- langchain 0.2.16 / langchain-openai 0.1.23
- openai 1.51.0
- 模型:gpt-4o-mini(temperature=0,tool_choice="auto")
- 运行机器:M2 MacBook Air 16G
二、方案设计:一个最小可用的Agent循环
我把Agent拆成四个职责单一的部分,这样每一块都能单独测试:
- Tool Registry(工具定义):用Pydantic定义参数schema,注册成OpenAI function calling格式。工具本身是普通Python函数,返回值统一序列化成字符串。
- Memory(记忆管理):维护一个消息列表,但只保留最近N轮完整对话 + 系统提示 + 所有工具调用摘要。原始实现里我直接全量塞,结果第6轮就顶到8k token。
- Error Handler(错误处理):工具执行包一层try/except,失败时不是抛给LLM,而是把错误信息作为
ToolMessage回填,让模型自己决定重试还是换路。 - Loop Controller(循环控制):设
max_iterations=8,同时加一个"连续两次相同工具+相同参数"的重复检测,命中就强制终止并返回部分结果。
这个设计的关键取舍是:把错误当成一种观察结果,而不是异常。这是Agent和普通函数调用最大的思维差异。
三、核心实现:工具定义与记忆管理
先看工具定义。LangChain的@tool装饰器会自动从docstring和类型注解生成schema,但我建议显式写args_schema,因为模型对参数描述的敏感度远超你的想象——我一开始没写description,模型把"城市名"和"国家名"搞混了三次。
# tools.py
from langchain_core.tools import tool
from pydantic import BaseModel, Field
import random
class WeatherInput(BaseModel):
city: str = Field(description="城市中文名,例如:北京、上海")
date: str = Field(default="today", description="日期,格式YYYY-MM-DD,默认today")
@tool("get_weather", args_schema=WeatherInput)
def get_weather(city: str, date: str = "today") -> str:
"""查询指定城市某天的天气,返回温度和天气状况。"""
# 模拟外部API,真实场景替换为requests调用
if city not in {"北京", "上海", "广州", "深圳"}:
raise ValueError(f"不支持的城市: {city},仅支持一线城市")
temp = random.randint(5, 32)
return f"{city} {date} 天气:晴,气温 {temp}°C"
class CalcInput(BaseModel):
expression: str = Field(description="合法的Python算术表达式,例如 32-5")
@tool("calculator", args_schema=CalcInput)
def calculator(expression: str) -> str:
"""执行简单算术运算,仅支持 + - * / 和括号。"""
allowed = set("0123456789+-*/(). ")
if not set(expression) list[BaseMessage]:
system = [m for m in messages if isinstance(m, SystemMessage)]
rest = [m for m in messages if not isinstance(m, SystemMessage)]
# 保留最近 max_rounds 轮(一轮≈一条AIMessage+若干ToolMessage)
kept, rounds = [], 0
for m in reversed(rest):
if isinstance(m, AIMessage) and m.tool_calls:
rounds += 1
if rounds > self.max_rounds:
break
kept.append(m)
kept.reverse()
# 二次保护:字符数超限时丢弃最旧的完整轮次
while sum(len(str(m.content)) for m in kept) > self.max_chars and kept:
kept.pop(0)
return system + kept
实测这个策略把"查天气→算温差→写报告"任务的峰值token从7900降到3100,降幅61%,而任务成功率没变。原因是工具调用摘要本身就包含了关键中间结果,模型不需要看完整的历史tool输出。
四、错误处理与循环控制:让Agent自己从坑里爬出来
错误处理的核心代码就十几行,但效果立竿见影:
# executor.py
import time
from langchain_core.messages import ToolMessage
def safe_execute(tool, tool_call, retries: int = 1):
for attempt in range(retries + 1):
try:
result = tool.invoke(tool_call["args"])
return ToolMessage(content=str(result), tool_call_id=tool_call["id"])
except Exception as e:
if attempt == retries:
return ToolMessage(
content=f"工具执行失败:{type(e).__name__}: {e}。"
f"请检查参数或改用其他工具,不要重复相同调用。",
tool_call_id=tool_call["id"],
)
time.sleep(0.3 * (attempt + 1)) # 指数退避
注意最后那句提示词"不要重复相同调用"——这是我在踩坑后加的。没这句话时,模型在get_weather("杭州")失败后会连续重试同一参数,因为错误信息里只有"不支持的城市",它不知道该换什么。加上明确指令后,重复调用率从23%降到4%。
循环控制除了max_iterations,我还加了一个签名去重:
def run_agent(agent_llm, tools, user_input, max_iterations=8):
seen = set()
messages = [SystemMessage(content=SYSTEM_PROMPT), HumanMessage(content=user_input)]
for i in range(max_iterations):
ai = agent_llm.invoke(messages) # 已绑定 tools
messages.append(ai)
if not ai.tool_calls:
return ai.content, i + 1
for tc in ai.tool_calls:
sig = (tc["name"], tuple(sorted(tc["args"].items())))
if sig in seen:
messages.append(ToolMessage(
content="检测到重复调用,已跳过。请基于已有信息直接给出结论。",
tool_call_id=tc["id"]))
continue
seen.add(sig)
tool = next(t for t in tools if t.name == tc["name"])
messages.append(safe_execute(tool, tc))
messages = WindowMemory().trim(messages)
return "达到最大迭代次数,返回部分结果", max_iterations
SYSTEM_PROMPT里我明确写了三件事:先规划再调工具、每次只调一个工具、拿到足够信息就停止。这三句话让平均迭代轮次从6.1降到4.2。
五、踩坑记录与优化数据
几个真实的坑:
tool_choice="auto"+ 空tools列表会直接报400,务必保证至少注册一个工具。- ToolMessage的
tool_call_id必须和AIMessage里的id严格对应,否则LangChain会校验失败。我早期手动拼消息时漏了这个字段,排查了半小时。 - temperature别设0.7。Agent场景下0.7会让模型在"该调工具还是该回答"之间摇摆,实测0.0时工具调用准确率92%,0.7时只有74%。
- eval的安全性:calculator里我用了
{"__builtins__": {}}做沙箱,但这不够,生产环境应该用ast.literal_eval或专用解析器,别学我图省事。
效果数据(100次随机任务回放,任务为"查两城天气+算温差+生成一句话报告"):
| 指标 | 朴素实现 | 本文实现 |
|---|---|---|
| 任务成功率 | 71% | 94% |
| 平均迭代轮次 | 6.1 | 4.2 |
| 峰值token(P95) | 7900 | 3100 |
| P95端到端延迟 | 6.4s | 3.8s |
| 错误自恢复率 | 52% | 87% |
延迟主要花在模型调用上,gpt-4o-mini单次约600-900ms,4.2轮就是3秒左右,工具本身是毫秒级。想再压延迟,可以把"规划"和"执行"拆成两个不同模型,规划用mini、执行用更小模型,不过这是另一个话题了。
六、总结
手写Agent最大的收获不是代码,而是理解了一件事:Agent的可靠性不来自模型多强,而来自你对循环边界的控制。工具schema写清楚、错误信息带指令、记忆做分层裁剪、循环加去重和上限,这四件事做到位,gpt-4o-mini这种便宜模型也能跑出94%的任务成功率。
如果你要往生产走,下一步建议是:把safe_execute换成带超时和熔断的版本(我用concurrent.futures加了3秒超时),以及把记忆换成向量检索+窗口的混合方案。代码我都放在本地仓库里跑通了,上面两段核心代码可以直接复制进你的项目改。