一、为什么我要手写一个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}"

几个设计决策值得说:

  1. 错误不抛,回灌。工具报错时把错误字符串作为ToolMessage塞回去,模型下一轮看到"参数X应该是int你传了str"就能自己改。实测这一招让一次成功率涨了约20个点。
  2. 重复调用计数用全局限流而非滑动窗口,简单粗暴但有效。我们场景下单任务一个工具调用超3次基本就是跑飞了。
  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消息的配对完整性。下一步我打算把工具执行做成异步并行,现在串行跑多个工具调用还是有点浪费——这个等有数据了再写一篇。

代码全部可直接运行,缺的依赖就那四个包,版本在上面。有问题评论区聊。