一、问题背景:为什么我要手写一个Agent

先说结论:LangChain的AgentExecutor和AutoGPT的循环范式都很好用,但如果你没手写过一遍,遇到问题基本只能靠猜。

我最近在做内部知识库问答助手,需求很朴素:用户提问 → 模型判断要不要查工具 → 调用工具 → 根据结果继续判断 → 直到能回答。一开始直接上LangChain 0.2.16的create_openai_tools_agent + AgentExecutor,跑通只花了半小时,但上线后遇到几个问题:

  1. 模型偶尔输出格式错误的工具调用JSON,AgentExecutor直接抛OutputParserException,整个链路挂掉;
  2. 多轮对话里模型反复调用同一个工具,陷入死循环,烧token;
  3. 记忆只是简单拼接历史消息,超过上下文窗口就报错,没有裁剪策略;
  4. 出错后没有重试,一次工具超时整轮失败。

这些问题在框架里都有对应的配置项(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(示例中省略了部分日志代码),拿去改改就能接自己的工具。