一、问题背景:为什么我要手写一个Agent
先说结论:LangChain的AgentExecutor和AutoGPT的循环范式都很好用,但如果你没手写过一遍,遇到问题基本只能靠猜。
我最近在做内部知识库问答助手,需求很朴素:用户提问 → 模型判断要不要查工具 → 调用工具 → 根据结果继续判断 → 直到能回答。一开始直接上LangChain 0.2.16的create_openai_tools_agent + AgentExecutor,跑通只花了半小时,但上线后遇到几个问题:
- 模型偶尔输出格式错误的工具调用JSON,
AgentExecutor直接抛OutputParserException,整个链路挂掉; - 多轮对话里模型反复调用同一个工具,陷入死循环,烧token;
- 记忆只是简单拼接历史消息,超过上下文窗口就报错,没有裁剪策略;
- 出错后没有重试,一次工具超时整轮失败。
这些问题在框架里都有对应的配置项(max_iterations、handle_parsing_errors、max_execution_time),但文档分散,且不同版本行为不一致。于是我决定手写一遍,把工具定义、记忆管理、错误处理、循环控制这四件事的细节彻底搞清楚。本文就是这次实践的完整记录。
二、环境与版本
- Python 3.11.9
- OpenAI SDK 1.40.0(用
gpt-4o-mini,便宜且工具调用稳定) - LangChain 0.2.16(仅用于对比,自研Agent不依赖它)
- tiktoken 0.7.0(token计数)
- 运行环境:macOS 14.5 / 8核16G
自研Agent核心代码不依赖任何Agent框架,只用openai官方SDK,方便你移植到任何模型。
三、方案设计:Agent的四根支柱
一个最小可用的Agent循环,本质是下面这个伪代码:
while 未超过最大轮数:
response = LLM(messages, tools)
if response 是最终答案:
return answer
for tool_call in response.tool_calls:
result = 执行工具(tool_call) # 带错误处理
messages.append(tool_result)
messages = 记忆管理(messages) # 裁剪/压缩
对应四个模块:
- 工具定义:用JSON Schema描述工具,让模型能正确生成调用参数;
- 记忆管理:消息列表的增删策略,控制token上限;
- 错误处理:工具执行异常、模型输出解析异常、超时,三类分别处理;
- 循环控制:最大轮数、重复调用检测、提前终止条件。
下面逐个实现。
四、核心实现(含代码)
4.1 工具定义
工具定义的关键是Schema要"窄"——参数越少、类型越明确,模型调用越准。我用一个装饰器把Python函数注册成工具:
import json
import inspect
from typing import Callable, get_type_hints
class Tool:
def __init__(self, func: Callable, name: str, description: str):
self.func = func
self.name = name
self.description = description
self.schema = self._build_schema()
def _build_schema(self):
hints = get_type_hints(self.func)
params = inspect.signature(self.func).parameters
type_map = {str: "string", int: "integer", float: "number", bool: "boolean"}
properties = {}
required = []
for pname, p in params.items():
properties[pname] = {"type": type_map.get(hints.get(pname, str), "string")}
if p.default is inspect.Parameter.empty:
required.append(pname)
return {
"type": "function",
"function": {
"name": self.name,
"description": self.description,
"parameters": {
"type": "object",
"properties": properties,
"required": required,
},
},
}
def run(self, **kwargs):
return self.func(**kwargs)
# 注册两个示例工具
def search_kb(query: str) -> str:
"""模拟知识库检索"""
fake_db = {"退款": "退款政策:7天无理由...", "发票": "发票申请流程:..."}
for k, v in fake_db.items():
if k in query:
return v
return "未找到相关内容"
def get_order_status(order_id: str) -> str:
"""模拟订单查询"""
if order_id.startswith("ORD"):
return f"订单{order_id}状态:已发货"
return "订单号格式错误,应以ORD开头"
tools = [
Tool(search_kb, "search_kb", "在内部知识库中检索问题答案,参数为查询关键词"),
Tool(get_order_status, "get_order_status", "根据订单号查询订单状态"),
]
注意两点:一是description要写清楚"什么时候用",模型靠这个判断是否调用;二是必填参数标记required,否则模型可能漏传。
4.2 记忆管理
记忆管理的核心是token预算。我的策略是:系统提示 + 最近N轮完整保留,更早的消息做摘要压缩。这里给一个简化但够用的版本——按token数从旧到新裁剪,且保证tool消息不被单独丢弃(否则会破坏消息结构):
import tiktoken
enc = tiktoken.encoding_for_model("gpt-4o-mini")
def count_tokens(messages):
total = 0
for m in messages:
total += len(enc.encode(str(m.get("content", "")))) + 4
return total
def trim_messages(messages, max_tokens=3000, keep_recent=6):
"""保留system + 最近keep_recent条,超预算则从旧的非system消息开始删"""
if count_tokens(messages) max_tokens and len(rest) > keep_recent:
rest.pop(0)
# 清理孤儿tool消息(前面没有assistant的tool_call)
cleaned = []
for m in rest:
if m["role"] == "tool" and (not cleaned or cleaned[-1]["role"] not in ("assistant",)):
continue
cleaned.append(m)
return system + cleaned
max_tokens=3000是给gpt-4o-mini留的余量(上下文128k,但我不想让历史无限膨胀导致延迟上升)。实测10轮对话下裁剪触发率约20%,响应延迟稳定在1.8s左右。
4.3 错误处理与循环控制
这是最容易踩坑的部分。三类错误分开处理:
- 工具执行异常:捕获后把错误信息作为
tool消息回传给模型,让它自己决定重试还是换工具; - 模型输出解析异常:
tool_calls格式错误时,追加一条user消息"请以正确格式重新调用",最多重试2次; - 死循环检测:记录连续相同工具+参数的调用,超过2次直接终止并返回兜底答案。
完整循环实现:
from openai import OpenAI
import time
import hashlib
client = OpenAI(api_key="sk-xxx")
def call_llm(messages, tool_schemas, retries=2):
for i in range(retries + 1):
try:
return client.chat.completions.create(
model="gpt-4o-mini",
messages=messages,
tools=tool_schemas,
tool_choice="auto",
temperature=0.2,
timeout=20,
)
except Exception as e:
if i == retries:
raise
time.sleep(1.5 * (i + 1)) # 指数退避
def run_agent(user_input: str, max_iterations=6) -> str:
messages = [
{"role": "system", "content": "你是内部助手,需要时调用工具,不要编造。"},
{"role": "user", "content": user_input},
]
tool_map = {t.name: t for t in tools}
tool_schemas = [t.schema for t in tools]
call_history = []
for step in range(max_iterations):
messages = trim_messages(messages)
resp = call_llm(messages, tool_schemas)
msg = resp.choices[0].message
if not msg.tool_calls:
return msg.content or "(模型未返回内容)"
messages.append({
"role": "assistant",
"content": msg.content,
"tool_calls": [tc.model_dump() for tc in msg.tool_calls],
})
for tc in msg.tool_calls:
name = tc.function.name
args = json.loads(tc.function.arguments or "{}")
# 死循环检测
sig = hashlib.md5(f"{name}{json.dumps(args, sort_keys=True)}".encode()).hexdigest()
call_history.append(sig)
if call_history.count(sig) > 2:
return "检测到重复调用,已终止。请补充更多信息后重试。"
# 工具执行 + 错误兜底
if name not in tool_map:
result = f"错误:工具 {name} 不存在"
else:
try:
result = tool_map[name].run(**args)
except Exception as e:
result = f"工具执行失败:{type(e).__name__}: {e}"
messages.append({
"role": "tool",
"tool_call_id": tc.id,
"content": str(result)[:2000], # 截断超长结果
})
return "已达到最大轮数限制,未能得出最终答案。"
几个参数值得说:max_iterations=6(实测90%问题3轮内解决,6轮是安全上限)、temperature=0.2(工具调用场景低温度更稳)、工具结果[:2000]截断(防止一次检索塞爆上下文)。
4.4 和LangChain/AutoGPT的对比
跑通后我把同样任务接到LangChain 0.2.16的AgentExecutor上对比:
| 维度 | 自研Agent | LangChain AgentExecutor | AutoGPT式循环 |
|---|---|---|---|
| 代码量 | ~300行 | ~30行(配置) | 数千行(含规划模块) |
| 工具调用成功率 | 94% | 91% | 88% |
| 平均延迟 | 1.8s | 2.1s | 4.5s+ |
| 可控性 | 完全可控 | 需读源码调参 | 黑盒多 |
LangChain胜在生态(内置几十种工具、回调系统),但出问题时你得翻handle_parsing_errors、max_iterations、early_stopping_method这些参数的行为差异;AutoGPT的规划-反思循环适合开放式任务,但对"查个订单"这种确定性任务属于杀鸡用牛刀,延迟和token都翻倍。
五、踩坑与优化
坑1:工具结果里的特殊字符破坏消息结构。 早期直接把工具返回的JSON字符串塞进content,遇到换行和引号时模型解析出错。解决:工具结果统一str()并截断,复杂结构先json.dumps(ensure_ascii=False)。
坑2:裁剪记忆把tool消息和对应的assistant.tool_calls拆散。 OpenAI API会报tool_call_id not found。这就是上面trim_messages里做孤儿清理的原因——tool消息必须紧跟对应的assistant消息。
坑3:模型"假装"调用了工具。 有时模型在content里写"我将调用search_kb"但不实际返回tool_calls。解决:系统提示里明确"不要描述调用过程,直接调用",并在检测到content含工具名但无tool_calls时追加纠正消息。
优化:工具描述加few-shot。 在description里加一句"例如:用户问退款政策时调用,query传'退款'",工具调用准确率从62%提升到94%。这是投入产出比最高的一处改动。
六、效果数据
在50条真实用户问题上测试(含15条多轮、10条需工具、5条故意触发错误的边界case):
- 端到端成功率:92%(46/50),失败4条中3条是问题本身超纲;
- 平均轮数:2.3轮,最大6轮;
- 平均延迟:1.8s(P95 3.2s);
- 平均token消耗:每轮约850 tokens,比初版(无裁剪、无截断)降低约35%;
- 工具调用成功率:94%,错误全部被兜底捕获,无一次链路崩溃。
七、总结
手写Agent最大的收获不是"省了一个框架",而是搞清楚了四件事的边界:工具Schema要窄、记忆要有token预算、错误要回传给模型而不是抛给用户、循环要有硬上限和重复检测。这四点在LangChain里都是配置项,但配置项背后的行为,只有自己写一遍才心里有数。
如果你也在做Agent开发,建议先用框架快速验证,然后挑一个核心链路手写一遍做对照——遇到诡异问题时,这份代码就是你的调试底牌。完整代码约300行,已放在我的GitHub(示例中省略了部分日志代码),拿去改改就能接自己的工具。