一、为什么我要手写一个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循环,核心状态机只有四步:

  1. 把「系统提示 + 历史消息 + 可用工具schema」发给LLM
  2. LLM要么返回最终答案(finish_reason == "stop"),要么返回一个或多个 tool_calls
  3. 执行工具,把结果以 role="tool" 的消息追加进历史
  4. 检查步数、检查重复调用、检查错误次数,决定继续还是终止

记忆管理我做了两层:短期记忆是完整的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自主循环的底稿。真要上生产,还需要补:并发的工具调用、结构化日志、按消息组裁剪历史、以及给每次工具调用加超时。但骨架清楚了,剩下的都是工程问题。