为了搞清楚 Agent 框架背后到底在做什么,我不用任何框架,纯手写了一个带工具调用的 Agent Loop。代码不到 200 行,但该有的都有了。

核心抽象

一个 Agent 主循环其实就三件事:

while not done:
    response = llm(messages, tools=tool_schemas)
    if response.has_tool_calls:
        for call in response.tool_calls:
            result = dispatch(call)
            messages.append(tool_message(call.id, result))
    else:
        done = True
        answer = response.text

模型每轮要么输出最终答案,要么请求调用工具;调用结果作为新消息喂回去,进入下一轮。就这么简单——框架的价值在细节,而不在主循环。

工具的定义与分发

每个工具用 JSON Schema 描述:

TOOLS = {
    "search_wiki": {
        "description": "搜索维基百科,返回摘要",
        "parameters": {
            "query": {"type": "string", "description": "搜索关键词"}
        },
        "fn": search_wiki,
    },
    "calculator": {
        "description": "计算数学表达式",
        "parameters": {
            "expr": {"type": "string", "description": "如 3*(4+5)"}
        },
        "fn": lambda expr: str(eval(expr, {"__builtins__": {}})),
    },
}

分发就是按名字查表调用,把异常也包成字符串返回——让模型自己看到报错并重试,比在代码里硬处理容错效果好得多。

踩过的坑

1. 死循环

模型偶尔会在两个工具之间来回横跳。加了一个简单的防御:连续 3 次调用同一工具且参数相似时,往消息里插一条系统提示”请总结已知信息并作答”。

2. 上下文膨胀

搜索结果动辄几千 token。解决办法:每个工具的返回结果先截断到 800 字符,长文档让模型分次查询。

3. 工具描述的质量决定一切

同样的工具,描述从”搜索”改成”当需要查询事实性知识时使用,输入应为具体名词而非整句”之后,调用准确率明显提升。工具描述是写给人看的,更是写给模型看的。

收获

手写一遍之后再看 LangChain、AutoGen 这些框架,很多设计就了然了:状态机、检查点、人机回环,都是在朴素 Loop 上长出来的。建议每个做 Agent 的人都至少手写一次——框架会过时,主循环不会。

完整代码放在 GitHub 上了,欢迎交流。