一、为什么我要手写一个Agent,而不是直接用AutoGPT

先说结论:AutoGPT那套"自主目标分解"在Demo里很惊艳,但落到生产环境,问题很集中——它的规划循环不透明、token消耗不可控、工具失败后容易陷入重复调用。我上一个项目用AutoGPT风格的框架跑数据采集Agent,一个"整理竞品价格"的任务烧了12万token还没收敛,最后发现是它把"打开网页失败"当成了"需要再打开一次"。

LangChain 0.2.x的AgentExecutor给了我们一个更可控的骨架:它把"LLM决策 → 工具执行 → 观察结果回填 → 再决策"这个循环显式暴露出来,循环上限、异常处理、记忆管理都能自己插手。所以这篇文章我不讲怎么调包,而是把这个循环拆开,用约300行代码手写一遍。你会看到四个核心模块的真实实现:工具定义、记忆管理、错误处理、循环控制。

环境版本先交代清楚,避免你复现时踩版本坑:

  • Python 3.11.7
  • langchain 0.2.16 / langchain-openai 0.1.23
  • openai 1.51.0
  • 模型:gpt-4o-mini(temperature=0,tool_choice="auto")
  • 运行机器:M2 MacBook Air 16G

二、方案设计:一个最小可用的Agent循环

我把Agent拆成四个职责单一的部分,这样每一块都能单独测试:

  1. Tool Registry(工具定义):用Pydantic定义参数schema,注册成OpenAI function calling格式。工具本身是普通Python函数,返回值统一序列化成字符串。
  2. Memory(记忆管理):维护一个消息列表,但只保留最近N轮完整对话 + 系统提示 + 所有工具调用摘要。原始实现里我直接全量塞,结果第6轮就顶到8k token。
  3. Error Handler(错误处理):工具执行包一层try/except,失败时不是抛给LLM,而是把错误信息作为ToolMessage回填,让模型自己决定重试还是换路。
  4. Loop Controller(循环控制):设max_iterations=8,同时加一个"连续两次相同工具+相同参数"的重复检测,命中就强制终止并返回部分结果。

这个设计的关键取舍是:把错误当成一种观察结果,而不是异常。这是Agent和普通函数调用最大的思维差异。

三、核心实现:工具定义与记忆管理

先看工具定义。LangChain的@tool装饰器会自动从docstring和类型注解生成schema,但我建议显式写args_schema,因为模型对参数描述的敏感度远超你的想象——我一开始没写description,模型把"城市名"和"国家名"搞混了三次。

# tools.py
from langchain_core.tools import tool
from pydantic import BaseModel, Field
import random

class WeatherInput(BaseModel):
    city: str = Field(description="城市中文名,例如:北京、上海")
    date: str = Field(default="today", description="日期,格式YYYY-MM-DD,默认today")

@tool("get_weather", args_schema=WeatherInput)
def get_weather(city: str, date: str = "today") -> str:
    """查询指定城市某天的天气,返回温度和天气状况。"""
    # 模拟外部API,真实场景替换为requests调用
    if city not in {"北京", "上海", "广州", "深圳"}:
        raise ValueError(f"不支持的城市: {city},仅支持一线城市")
    temp = random.randint(5, 32)
    return f"{city} {date} 天气:晴,气温 {temp}°C"

class CalcInput(BaseModel):
    expression: str = Field(description="合法的Python算术表达式,例如 32-5")

@tool("calculator", args_schema=CalcInput)
def calculator(expression: str) -> str:
    """执行简单算术运算,仅支持 + - * / 和括号。"""
    allowed = set("0123456789+-*/(). ")
    if not set(expression)  list[BaseMessage]:
        system = [m for m in messages if isinstance(m, SystemMessage)]
        rest = [m for m in messages if not isinstance(m, SystemMessage)]
        # 保留最近 max_rounds 轮(一轮≈一条AIMessage+若干ToolMessage)
        kept, rounds = [], 0
        for m in reversed(rest):
            if isinstance(m, AIMessage) and m.tool_calls:
                rounds += 1
                if rounds > self.max_rounds:
                    break
            kept.append(m)
        kept.reverse()
        # 二次保护:字符数超限时丢弃最旧的完整轮次
        while sum(len(str(m.content)) for m in kept) > self.max_chars and kept:
            kept.pop(0)
        return system + kept

实测这个策略把"查天气→算温差→写报告"任务的峰值token从7900降到3100,降幅61%,而任务成功率没变。原因是工具调用摘要本身就包含了关键中间结果,模型不需要看完整的历史tool输出。

四、错误处理与循环控制:让Agent自己从坑里爬出来

错误处理的核心代码就十几行,但效果立竿见影:

# executor.py
import time
from langchain_core.messages import ToolMessage

def safe_execute(tool, tool_call, retries: int = 1):
    for attempt in range(retries + 1):
        try:
            result = tool.invoke(tool_call["args"])
            return ToolMessage(content=str(result), tool_call_id=tool_call["id"])
        except Exception as e:
            if attempt == retries:
                return ToolMessage(
                    content=f"工具执行失败:{type(e).__name__}: {e}。"
                            f"请检查参数或改用其他工具,不要重复相同调用。",
                    tool_call_id=tool_call["id"],
                )
            time.sleep(0.3 * (attempt + 1))  # 指数退避

注意最后那句提示词"不要重复相同调用"——这是我在踩坑后加的。没这句话时,模型在get_weather("杭州")失败后会连续重试同一参数,因为错误信息里只有"不支持的城市",它不知道该换什么。加上明确指令后,重复调用率从23%降到4%。

循环控制除了max_iterations,我还加了一个签名去重:

def run_agent(agent_llm, tools, user_input, max_iterations=8):
    seen = set()
    messages = [SystemMessage(content=SYSTEM_PROMPT), HumanMessage(content=user_input)]
    for i in range(max_iterations):
        ai = agent_llm.invoke(messages)  # 已绑定 tools
        messages.append(ai)
        if not ai.tool_calls:
            return ai.content, i + 1
        for tc in ai.tool_calls:
            sig = (tc["name"], tuple(sorted(tc["args"].items())))
            if sig in seen:
                messages.append(ToolMessage(
                    content="检测到重复调用,已跳过。请基于已有信息直接给出结论。",
                    tool_call_id=tc["id"]))
                continue
            seen.add(sig)
            tool = next(t for t in tools if t.name == tc["name"])
            messages.append(safe_execute(tool, tc))
        messages = WindowMemory().trim(messages)
    return "达到最大迭代次数,返回部分结果", max_iterations

SYSTEM_PROMPT里我明确写了三件事:先规划再调工具、每次只调一个工具、拿到足够信息就停止。这三句话让平均迭代轮次从6.1降到4.2。

五、踩坑记录与优化数据

几个真实的坑:

  1. tool_choice="auto" + 空tools列表会直接报400,务必保证至少注册一个工具。
  2. ToolMessage的tool_call_id必须和AIMessage里的id严格对应,否则LangChain会校验失败。我早期手动拼消息时漏了这个字段,排查了半小时。
  3. temperature别设0.7。Agent场景下0.7会让模型在"该调工具还是该回答"之间摇摆,实测0.0时工具调用准确率92%,0.7时只有74%。
  4. eval的安全性:calculator里我用了{"__builtins__": {}}做沙箱,但这不够,生产环境应该用ast.literal_eval或专用解析器,别学我图省事。

效果数据(100次随机任务回放,任务为"查两城天气+算温差+生成一句话报告"):

指标 朴素实现 本文实现
任务成功率 71% 94%
平均迭代轮次 6.1 4.2
峰值token(P95) 7900 3100
P95端到端延迟 6.4s 3.8s
错误自恢复率 52% 87%

延迟主要花在模型调用上,gpt-4o-mini单次约600-900ms,4.2轮就是3秒左右,工具本身是毫秒级。想再压延迟,可以把"规划"和"执行"拆成两个不同模型,规划用mini、执行用更小模型,不过这是另一个话题了。

六、总结

手写Agent最大的收获不是代码,而是理解了一件事:Agent的可靠性不来自模型多强,而来自你对循环边界的控制。工具schema写清楚、错误信息带指令、记忆做分层裁剪、循环加去重和上限,这四件事做到位,gpt-4o-mini这种便宜模型也能跑出94%的任务成功率。

如果你要往生产走,下一步建议是:把safe_execute换成带超时和熔断的版本(我用concurrent.futures加了3秒超时),以及把记忆换成向量检索+窗口的混合方案。代码我都放在本地仓库里跑通了,上面两段核心代码可以直接复制进你的项目改。