一、为什么我要手写一个Agent
先说结论:用LangChain的AgentExecutor能跑通demo,但一到线上就抓瞎。
上个月接了个内部工单系统自动化的需求,需要Agent能查数据库、调HTTP接口、做多步推理。一开始直接用create_openai_tools_agent + AgentExecutor,三天搭完demo,然后踩了一周坑:工具报错直接抛异常中断整个循环、记忆无限增长把token打爆、模型陷入"调用工具→拿到结果→再调同一个工具"的死循环。想改?AgentExecutor内部逻辑封装得死死的,只能去翻源码。
后来索性花两天手写了一个200行左右的Agent核心,把工具定义、记忆、错误处理、循环控制全部摊开。这篇文章就是那次重构的完整记录。如果你也遇到"框架能跑但改不动"的问题,这篇应该对你有用。
二、环境与版本
先锁死版本,Agent这块API变动很频繁,版本不对代码大概率跑不起来:
Python 3.11.9
langchain 0.2.16
langchain-openai 0.1.23
langchain-core 0.2.38
openai 1.40.0
pydantic 2.8.2
模型用gpt-4o-mini,temperature设为0(Agent场景下随机性基本是负资产),max_tokens=1024。为什么不用AutoGPT?AutoGPT那套自主目标分解对我们这种"流程明确、工具有限"的工单场景是杀鸡用牛刀,而且它内部循环没有明确的终止条件控制,容易跑飞。AutoGPT适合开放式探索,LangChain的Tool Calling机制适合受控流程,我们走后者路线,但循环控制自己写。
三、方案设计:四个模块拆开看
手写Agent的核心就四件事,我画了个简单的数据流:
用户输入 → [记忆注入] → LLM推理 → 有tool_calls?
├─ 是 → [执行工具+错误捕获] → 结果写回记忆 → 回到LLM
└─ 否 → 输出最终答案
- 工具定义:用Pydantic schema描述参数,转成OpenAI function calling格式
- 记忆管理:滑动窗口 + token预算裁剪,保留system prompt和最近N轮
- 错误处理:工具级try/except,错误信息作为
ToolMessage回灌给模型让它自我修正 - 循环控制:最大迭代次数 + 重复调用检测 + 超时熔断
下面逐个给实现。
四、核心实现
4.1 工具定义
不用LangChain的@tool装饰器(它内部又包了一层,调试时栈太深),直接手写schema。关键点是参数描述要写给模型看,模型靠这个决定传什么值:
from pydantic import BaseModel, Field
from typing import Callable, Any
import json
class ToolSchema(BaseModel):
"""工具参数schema基类"""
class WeatherInput(ToolSchema):
city: str = Field(description="城市名称,中文,如'北京'")
unit: str = Field(default="celsius", description="温度单位,celsius或fahrenheit")
class Tool:
def __init__(self, name: str, description: str,
args_schema: type[ToolSchema], func: Callable):
self.name = name
self.description = description
self.args_schema = args_schema
self.func = func
def to_openai_schema(self) -> dict:
"""转成OpenAI function calling格式"""
return {
"type": "function",
"function": {
"name": self.name,
"description": self.description,
"parameters": self.args_schema.model_json_schema(),
}
}
def run(self, **kwargs) -> str:
# 参数校验在调用前做,不合法直接抛给上层捕获
validated = self.args_schema(**kwargs)
result = self.func(**validated.model_dump())
return str(result)[:2000] # 截断,防止单个工具结果撑爆上下文
注意最后那个[:2000]截断,这是踩坑换来的——有个查日志的工具返回了8万字符,直接把下一轮请求顶到context_length_exceeded。
4.2 记忆管理
记忆这块最容易出问题。我的策略是双缓冲:完整历史存内存用于审计,送给模型的是裁剪后的窗口。
from langchain_core.messages import BaseMessage, SystemMessage, HumanMessage, AIMessage, ToolMessage
class Memory:
def __init__(self, system_prompt: str, max_tokens: int = 6000, keep_recent: int = 8):
self.system = SystemMessage(content=system_prompt)
self.history: list[BaseMessage] = []
self.max_tokens = max_tokens
self.keep_recent = keep_recent
def add(self, msg: BaseMessage):
self.history.append(msg)
def _estimate_tokens(self, msgs: list[BaseMessage]) -> int:
# 粗估:中文约1.5字符/token,英文约4字符/token,取保守值2
return sum(len(m.content or "") for m in msgs) // 2
def get_context(self) -> list[BaseMessage]:
ctx = [self.system] + self.history
# 超预算就从最老的开始丢,但保留最近keep_recent条
while self._estimate_tokens(ctx) > self.max_tokens and len(ctx) > self.keep_recent + 1:
ctx.pop(1) # 保留system,从第一条历史开始删
return ctx
def clear_tool_messages(self):
"""清理中间工具消息,只保留问答对(可选策略)"""
self.history = [m for m in self.history if not isinstance(m, ToolMessage)]
这里有个细节:ToolMessage不能随便删。OpenAI的API要求assistant消息里的tool_calls必须跟对应的tool消息成对出现,删一半会报400。所以我上面clear_tool_messages只在会话结束时用,运行中绝不能动。
4.3 循环控制 + 错误处理(Agent主循环)
这是全文核心,把四件事串起来:
import time, json
from openai import OpenAI, APIError, RateLimitError
from langchain_core.messages import AIMessage, HumanMessage, ToolMessage
class SimpleAgent:
def __init__(self, tools: list[Tool], system_prompt: str,
model: str = "gpt-4o-mini", max_iterations: int = 6,
timeout_seconds: int = 60):
self.client = OpenAI()
self.tools = {t.name: t for t in tools}
self.tool_schemas = [t.to_openai_schema() for t in tools]
self.memory = Memory(system_prompt)
self.model = model
self.max_iterations = max_iterations
self.timeout = timeout_seconds
self.call_counts: dict[str, int] = {} # 检测重复调用
def _call_llm(self, ctx: list[BaseMessage]):
messages = []
for m in ctx:
if isinstance(m, HumanMessage):
messages.append({"role": "user", "content": m.content})
elif isinstance(m, AIMessage):
d = {"role": "assistant", "content": m.content or ""}
if getattr(m, "tool_calls", None):
d["tool_calls"] = m.tool_calls
messages.append(d)
elif isinstance(m, ToolMessage):
messages.append({"role": "tool", "tool_call_id": m.tool_call_id,
"content": m.content})
else:
messages.append({"role": "system", "content": m.content})
return self.client.chat.completions.create(
model=self.model, messages=messages,
tools=self.tool_schemas, temperature=0, max_tokens=1024,
)
def run(self, user_input: str) -> str:
self.memory.add(HumanMessage(content=user_input))
start = time.time()
for i in range(self.max_iterations):
# 超时熔断
if time.time() - start > self.timeout:
return f"[超时] 已执行{i}轮,超过{self.timeout}秒限制"
# LLM调用带重试
resp = None
for attempt in range(3):
try:
resp = self._call_llm(self.memory.get_context())
break
except RateLimitError:
time.sleep(2 ** attempt)
except APIError as e:
if attempt == 2:
return f"[LLM错误] {e}"
msg = resp.choices[0].message
ai_msg = AIMessage(content=msg.content or "",
tool_calls=[tc.model_dump() for tc in (msg.tool_calls or [])])
self.memory.add(ai_msg)
# 无工具调用 → 结束
if not msg.tool_calls:
return msg.content or ""
# 执行工具(每个tool_call独立错误捕获)
for tc in msg.tool_calls:
name = tc.function.name
self.call_counts[name] = self.call_counts.get(name, 0) + 1
# 重复调用检测:同一工具超3次强制中断
if self.call_counts[name] > 3:
return f"[循环中止] 工具{name}被重复调用{self.call_counts[name]}次,疑似死循环"
try:
args = json.loads(tc.function.arguments)
result = self.tools[name].run(**args)
except KeyError:
result = f"错误:工具{name}不存在,可用工具:{list(self.tools)}"
except Exception as e:
result = f"工具执行失败:{type(e).__name__}: {e}。请检查参数或换用其他方式。"
self.memory.add(ToolMessage(content=result, tool_call_id=tc.id))
return f"[达到最大迭代{self.max_iterations}轮] 最后输出:{self.memory.history[-1].content}"
几个设计决策值得说:
- 错误不抛,回灌。工具报错时把错误字符串作为
ToolMessage塞回去,模型下一轮看到"参数X应该是int你传了str"就能自己改。实测这一招让一次成功率涨了约20个点。 - 重复调用计数用全局限流而非滑动窗口,简单粗暴但有效。我们场景下单任务一个工具调用超3次基本就是跑飞了。
- 超时用墙钟时间,不是迭代数。因为LLM单次响应可能就10秒,6轮迭代理论上能跑一分钟以上。
4.4 跑起来
def get_weather(city: str, unit: str = "celsius") -> str:
return f"{city}当前温度22度({unit}),晴"
agent = SimpleAgent(
tools=[Tool("get_weather", "查询指定城市实时天气", WeatherInput, get_weather)],
system_prompt="你是一个助手,需要天气信息时调用get_weather工具。回答简洁。",
)
print(agent.run("北京和上海今天天气怎么样?"))
模型会并行发起两个get_weather调用(gpt-4o-mini支持parallel tool calls),一轮拿回两个结果,第二轮直接汇总输出。实测这个query平均1.2秒完成,2次工具调用。
五、踩坑与优化
坑1:tool_calls序列化丢失。AIMessage构造时如果直接传tool_calls=[tc](OpenAI对象),LangChain序列化会报错,必须.model_dump()成dict。这个错误信息很误导,报的是pydantic校验失败。
坑2:并行工具调用的顺序。模型一次返回多个tool_call时,ToolMessage必须按tool_call_id一一对应,顺序无所谓但id不能错。我一开始图省事用列表下标对应,遇到模型返回顺序和tool_calls数组不一致时直接400。
坑3:记忆裁剪把tool_call对拆散。前面提过,get_context里pop(1)如果正好删掉assistant(tool_calls)而保留tool消息,API直接拒绝。修复办法:裁剪时检查,如果删的是带tool_calls的assistant消息,把后续连续tool消息一起删。生产版我加了这个逻辑,博客里为简洁省略了。
优化数据(内部工单场景,200条测试query):
| 指标 | 裸AgentExecutor | 手写版(含错误回灌+循环控制) |
|---|---|---|
| 任务成功率 | 62% | 89% |
| 平均工具调用次数 | 2.4 | 1.8 |
| 死循环中断率 | 11% | 0.5% |
| P95延迟 | 8.3s | 5.1s |
成功率提升主要来自错误回灌(模型自我修正)和重复调用熔断(避免把预算耗在死循环上)。
六、总结
手写Agent这200行代码,核心价值不在"造轮子",而在把控制权拿回来。LangChain和AutoGPT抽象得很好,但Agent这层逻辑跟业务强相关——你的工具长什么样、什么算死循环、错误怎么回灌,这些框架给不了通用答案。
几个可以直接抄走的结论:错误信息一定要回灌给模型而不是抛异常;重复调用检测比最大迭代数更早发现问题;记忆裁剪要保住tool_calls和tool消息的配对完整性。下一步我打算把工具执行做成异步并行,现在串行跑多个工具调用还是有点浪费——这个等有数据了再写一篇。
代码全部可直接运行,缺的依赖就那四个包,版本在上面。有问题评论区聊。