一、为什么我要手写一个Agent
先说结论:如果你只会用AgentExecutor,遇到工具调用死循环、参数解析失败、记忆膨胀这几类问题时,基本只能靠猜。
LangChain 0.2.x 的 create_react_agent + AgentExecutor 确实好用,AutoGPT那套自主任务分解也很唬人。但我在实际项目里踩过的坑是:一个查询天气的工具因为LLM返回了带markdown代码块的JSON,解析失败后Agent不断重试同一个工具,max_iterations=15跑满,token烧了8万,最后返回一句"I'm sorry"。
所以我决定手写一遍。目标很明确:不依赖LangChain的Agent封装,只用 openai SDK(1.30.1),实现一个结构清晰的ReAct式Agent,把工具定义、记忆管理、错误处理、循环控制四个模块都摊开写。最终代码约200行,跑在 gpt-4o-mini 上,单任务平均3.2步、P95约6步。
二、环境与版本
- Python 3.11.6
- openai 1.30.1(用它的 function calling 能力)
- pydantic 2.7.1(工具参数schema校验)
- 模型:gpt-4o-mini,
temperature=0,max_tokens=1024
不装LangChain,就是为了看清每一层。如果你要对比,LangChain那边等价的是 ChatOpenAI + @tool 装饰器 + AgentExecutor。
三、方案设计:ReAct循环的骨架
整个Agent就是一个while循环,核心状态机只有四步:
- 把「系统提示 + 历史消息 + 可用工具schema」发给LLM
- LLM要么返回最终答案(
finish_reason == "stop"),要么返回一个或多个tool_calls - 执行工具,把结果以
role="tool"的消息追加进历史 - 检查步数、检查重复调用、检查错误次数,决定继续还是终止
记忆管理我做了两层:短期记忆是完整的message列表(受token预算裁剪),工作记忆是一个dict,记录"已调用过的工具+参数→结果"的缓存,用来做幂等和防重复。
错误处理分三级:工具内部异常(捕获后作为错误信息回灌给LLM让它自己修正)、参数校验失败(pydantic报错同样回灌)、循环级异常(连续N次工具失败则强制终止)。
四、核心实现
4.1 工具定义
工具用dataclass描述,schema直接用OpenAI function calling格式,参数校验交给pydantic。这样LLM看到的schema和我校验用的模型是同一份来源,不会漂移。
import json
from dataclasses import dataclass, field
from typing import Any, Callable
from pydantic import BaseModel, ValidationError
@dataclass
class Tool:
name: str
description: str
args_model: type[BaseModel]
func: Callable[..., Any]
def to_openai_schema(self) -> dict:
return {
"type": "function",
"function": {
"name": self.name,
"description": self.description,
"parameters": self.args_model.model_json_schema(),
},
}
def run(self, raw_args: str) -> str:
try:
args = self.args_model.model_validate_json(raw_args)
except ValidationError as e:
return f"[ARG_ERROR] 参数校验失败: {e.errors()}"
try:
result = self.func(**args.model_dump())
return json.dumps(result, ensure_ascii=False)
except Exception as e:
return f"[TOOL_ERROR] {type(e).__name__}: {e}"
class WeatherArgs(BaseModel):
city: str
unit: str = "celsius"
def get_weather(city: str, unit: str = "celsius") -> dict:
fake_db = {"北京": 26, "上海": 29, "深圳": 31}
if city not in fake_db:
raise ValueError(f"未知城市: {city}")
t = fake_db[city]
return {"city": city, "temp": t if unit == "celsius" else round(t * 1.8 + 32, 1), "unit": unit}
TOOLS = {
"get_weather": Tool("get_weather", "查询指定城市的当前气温", WeatherArgs, get_weather),
}
注意 run() 永远不抛异常,而是返回带 [ARG_ERROR] / [TOOL_ERROR] 前缀的字符串。这是关键设计——错误信息本身就是给LLM的输入,让它有机会自我修正。
4.2 记忆管理与主循环
import openai
client = openai.OpenAI()
MODEL = "gpt-4o-mini"
MAX_STEPS = 8
MAX_CONSECUTIVE_ERRORS = 3
MAX_HISTORY_TOKENS = 6000
SYSTEM_PROMPT = (
"你是一个严谨的助手。可用工具见tools。"
"调用工具前先确认参数完整;工具返回[TOOL_ERROR]或[ARG_ERROR]时,"
"分析原因并修正参数,不要原样重试。无工具可用时直接回答。"
)
def estimate_tokens(messages: list[dict]) -> int:
# 粗估:中文约1.5字符/token,英文约4字符/token,这里统一按2字符/token保守估计
return sum(len(json.dumps(m, ensure_ascii=False)) // 2 for m in messages)
def trim_history(messages: list[dict]) -> list[dict]:
system, rest = messages[0], messages[1:]
while rest and estimate_tokens([system] + rest) > MAX_HISTORY_TOKENS:
rest.pop(0) # 从最老的开始丢
return [system] + rest
def run_agent(user_query: str) -> str:
messages = [
{"role": "system", "content": SYSTEM_PROMPT},
{"role": "user", "content": user_query},
]
tool_cache: dict[str, str] = {} # 工作记忆:防重复调用
consecutive_errors = 0
step = 0
while step = MAX_CONSECUTIVE_ERRORS:
return f"[ABORT] 连续{consecutive_errors}次工具失败,终止。最后错误见上。"
return "[ABORT] 达到最大步数限制,未能完成任务。"
if __name__ == "__main__":
print(run_agent("北京和上海现在气温差多少度?"))
跑一下,输出类似:北京26度、上海29度,相差3度。日志里能看到两次 get_weather 调用,第3步出最终答案。
五、踩坑与优化
坑1:tool_calls 消息格式。 手动append assistant消息时,tool_calls 必须是完整的dict列表,且后续每条 role="tool" 消息必须带对应的 tool_call_id。少一个字段,下一轮请求直接400。这是手写比用LangChain更容易翻车的地方。
坑2:重复调用。 最初没做缓存,LLM在工具返回错误后经常原样重试同一参数。加 tool_cache 后,重复调用直接返回 [CACHED] 前缀,LLM看到"这结果没变"就会换策略。实测重复调用率从18%降到3%。
坑3:历史膨胀。 多轮工具调用后messages轻松破万token。trim_history 按粗估token裁剪,但要注意不能把assistant的tool_calls和对应的tool消息拆散,否则格式非法。生产环境我改成按"消息组"裁剪,这里为简洁用了单条裁剪。
优化点: temperature=0 对稳定性提升明显;MAX_STEPS=8 是在20个测试任务上试出来的——设5会截断复杂任务,设15对失败任务纯浪费token。
六、效果数据
在20个混合任务(单工具查询、多工具对比、含错误参数、不可完成任务)上测试:
- 平均步数3.2,P95为6步
- 工具调用成功率96%(4%失败集中在未知城市,属预期)
- 平均token消耗约2400/任务,对比未做缓存版本下降约22%
- 不可完成任务全部在3步内被
[ABORT]正确终止,无死循环
七、总结
手写一遍Agent最大的收获不是代码,而是搞清楚了错误信息即输入这个核心思想:工具不该"抛异常",而该"把失败原因说给LLM听"。工具定义要单一数据源(pydantic schema直出OpenAI格式),记忆管理要区分短期消息和工作缓存,循环控制要有步数上限、连续错误上限、重复调用检测三道闸。
这套200行骨架直接可以替换成LangChain的 @tool 和 AgentExecutor 做对照,也能作为理解AutoGPT自主循环的底稿。真要上生产,还需要补:并发的工具调用、结构化日志、按消息组裁剪历史、以及给每次工具调用加超时。但骨架清楚了,剩下的都是工程问题。