徒手写一个 AI Agent:看穿 Function Calling 的本质

"Agent" 大概是这两年 AI 圈被提及最多的词。但很多教程一上来就是 LangChain、AutoGen 一堆框架,读者跟着抄完代码,依然不知道底层发生了什么。这篇文章反过来:不用任何 Agent 框架,只用官方 SDK 和百来行 Python,把 Agent 从零写出来。

而且我们连官方的 Function Calling 功能都不会急着用——会先用最原始的提示词,徒手造一个"工具调用"。你会亲眼看到:所谓函数调用,本质上只是一场你和模型之间的"纸条游戏",官方功能不过是厂商把这场游戏标准化、并在模型里深度微调过的工业级版本。看穿了这一层,Agent 的一切就都不神秘了。

读完这篇文章,你会:

真正理解大语言模型在做什么,以及它天生的三个局限;
徒手实现一遍 Function Calling,彻底搞懂它的本质(剧透:模型从来不执行任何函数);
用 Python 一步步写出一个能自主完成多步任务、并拥有跨会话记忆的 Agent;
认识 harness,知道如何打磨它:提示词、工具设计、错误处理、上下文管理、安全;
明白 Claude、Codex 乃至各类 Agent 产品,在你的 demo 之上还多做了哪些事。

第一章:大语言模型到底在做什么

要造 Agent,得先明白发动机是怎么转的。这一章不堆数学,每个概念都给你一个能"看见"的画面。

1.1 它是一台"超级输入法"

拿起手机打几个字:"今天天气真"——输入法的候选栏立刻蹦出"好""不错""热"。输入法在做的事情是:根据你已经打出的字,猜下一个词。

大语言模型(LLM)做的是同一件事,只有两处不同:

第一,它的"候选栏"里躺着十几万个候选(整个词表),而不是三五个;第二,它猜词时参考的不是前面几个字,而是前面的全部内容——可以长达几十万字。

这些候选的最小单位叫 token,可以理解为"字块":英文里大约 3/4 个单词是一个 token,中文里一个汉字通常对应 1~2 个 token。模型每走一步,会给词表里所有候选各算一个概率,然后从中选一个。

生成一句完整的回答,就是把"猜一个、拼上去、再猜下一个"这个动作循环几百次:

输入:"中国的首都是"
第 1 步 → 候选栏第一名 "北" → 拼接 → "中国的首都是北"
第 2 步 → 候选栏第一名 "京" → 拼接 → "中国的首都是北京"
第 3 步 → 候选栏第一名 "。" → 拼接 → "中国的首都是北京。"
第 4 步 → 候选栏第一名 <结束>  → 停止

这种"边猜边拼"的方式有个学名,叫自回归生成。API 里的 temperature 参数控制的就是"怎么从候选栏里选":设为 0,永远选概率第一的候选,输出最稳定;调高之后,偶尔会选中排名靠后的候选,更有创意,也更容易跑偏。

请记住这个"输入法"的画面,它是全文的地基:

模型的任何输出,都只是一串接龙出来的文字。没有例外。

1.2 它为什么会"聊天":两次训练 + 一个模板

上面的接龙能力来自预训练:把互联网上的文本几乎读了个遍,在"猜下一个词"这道题上做了万亿次练习。词猜得准的副产品,是把语法、常识乃至世界知识都压进了参数里。

但只做过预训练的模型是个"纯接龙选手",并不会好好回答问题。你输入"中国的首都是哪里?",它很可能接出:

这是小学地理试卷的第一道题。下列选项中……

从接龙的角度这完全合理——训练语料里,这句话后面跟着试卷内容的概率确实不低。它没有错,它只是没被教过"你现在是个助手"。

于是有了后训练:先喂给它几十万条"问题 → 优质回答"的范例,教会它助手该有的样子(监督微调,SFT);再让人类给它的多个回答排序打分,用强化学习把人类偏好压进模型(RLHF)。两步之后,接龙选手才变成助手。

最后一块拼图是对话模板。你在代码里传的是整齐的消息列表:

[
  {"role": "user", "content": "你好"},
  {"role": "assistant", "content": "你好!有什么可以帮你?"},
  {"role": "user", "content": "推荐一部电影"}
]

但在进入模型之前,这个列表会被拼装成一段带特殊记号的长文本,大致长这样:

<|user|>你好<|end|>
<|assistant|>你好!有什么可以帮你?<|end|>
<|user|>推荐一部电影<|end|>
<|assistant|>

模型收到的就是这么一整篇"写到一半的文档",它的任务从头到尾没有变过:接龙。只不过它在后训练中被反复教导——看到 <|assistant|> 这个记号,就该接出一段高质量的助手发言。

一句话总结这一节:"聊天"只是"接龙"套了一层格式的皮肤。 看穿这一点,下一章的 Function Calling 会变得毫不神秘。

1.3 三个关键推论(写 Agent 的理论基础)

从"超级输入法"这个本质,可以直接推出三个对开发者至关重要的事实:

推论一:模型没有记忆。 每次 API 调用都是一次独立的接龙,上一次调用发生了什么,它一无所知。所谓多轮对话,是你把完整历史重新发一遍造成的假象。这决定了 Agent 的核心数据结构,就是一个不断变长的 messages 列表。

推论二:模型只会吐字,不会"做事"。 它不能上网、不能读你的硬盘、不能执行代码。它的输出永远只是文字。想让它"做事",必须有一段真正的程序代替它去执行——这就是 Function Calling 存在的全部理由,也是下一章的主角。

推论三:知识是静态的,而且它会编。 模型的知识停在训练数据的截止时间,并且在不确定时可能一本正经地胡说(幻觉)。解药同样是工具:让它去查,而不是让它去猜。

这三个局限,恰好对应 Agent 的三块拼图:上下文管理、工具调用、信息获取。带着这个认知,进入本文最关键的一章。

第二章:Function Calling 的本质——先徒手造一个,再看官方的

2.1 思想实验:锁在小黑屋里的天才

现在你知道了:模型只会吐字。给它换一个更具体的形象——

想象一位知识渊博的天才,被锁在一间没有窗户的屋子里。屋门上只有一个信封口:你把写着问题的纸条塞进去,他把写着回答的纸条递出来。他不能出门、不能上网、不能碰你的电脑——他与世界的全部接触,只有纸条。

你想让他"帮忙查一下北京的天气",怎么办?他出不去,查不了。唯一的办法是:事先和他约定一个暗号。你在第一张纸条上写:

如果你需要查天气,就在纸条上写「查天气:城市名」,我看到后替你去查,再把结果写在纸条上递回来给你。

于是整个流程变成:

纸条塞进去: "用户问:北京冷不冷?" + 上面那条暗号约定
纸条递出来: "查天气:北京"
         (你跑腿去查,查到:晴,3°C)
纸条塞进去: "查询结果:晴,3°C"
纸条递出来: "北京今天晴,3°C,挺冷的,记得穿厚外套。"

注意:天才自始至终没有离开屋子,所有的"行动"都是屋子外面的你完成的。他做的仅仅是——按照约定的格式吐字。

这就是 Function Calling 的全部原理。不信?下面用 40 行 Python 把这场"纸条游戏"原样实现出来。

2.2 徒手实现一个工具调用(不用任何官方功能)

下面这段代码完全没有用到官方的 Function Calling 功能——没有 tools 参数,没有任何特殊接口,只有普通的对话请求。暗号约定全部写在提示词里,解析暗号靠一个正则表达式。

"""diy_function_call.py —— 不用官方功能,徒手实现工具调用"""
import json
import re
from openai import OpenAI

client = OpenAI(api_key="sk-你的key", base_url="https://api.deepseek.com")
MODEL = "deepseek-v4-flash"

# 这是真正干活的函数,普通 Python,和 AI 没有半点关系
def get_weather(city: str) -> str:
    fake_data = {"北京": "晴,3°C", "上海": "小雨,12°C"}
    return fake_data.get(city, f"没有找到「{city}」的天气数据")

# ★ 全部秘密都在这段提示词里:我们私下和模型约定了一个"暗号格式"
SYSTEM_PROMPT = """你是一个助手。你自己不知道实时天气,但你有一个帮手可以替你查。

当你需要查天气时,只输出一行下面格式的指令,不要输出任何别的文字:
{"tool": "get_weather", "city": "城市名"}

当你收到以 [工具结果] 开头的消息后,再用自然语言回答用户最初的问题。
不需要查天气的问题,直接正常回答即可。"""

messages = [
    {"role": "system", "content": SYSTEM_PROMPT},
    {"role": "user", "content": "上海今天什么天气?"},
]

# ---- 第一次请求:模型自己决定要不要"喊人帮忙" ----
reply = client.chat.completions.create(
    model=MODEL, messages=messages
).choices[0].message.content
print("模型输出:", reply)

# ---- 解析暗号:检查模型是不是在请求工具 ----
match = re.search(r'\{.*"tool".*\}', reply, re.DOTALL)
if match:
    call = json.loads(match.group())
    result = get_weather(call["city"])  # 解析出参数并执行
    print("本地执行:", result)          # ★ 真正执行函数的,是这一行 Python
    # ---- 把结果"塞回信封口",让模型接着说 ----
    messages.append({"role": "assistant", "content": reply})
    messages.append({"role": "user", "content": f"[工具结果] {result}"})
    final = client.chat.completions.create(
        model=MODEL, messages=messages
    ).choices[0].message.content
    print("最终回答:", final)
else:
    print("最终回答:", reply)  # 模型判断不需要工具,直接回答了

运行输出:

模型输出: {"tool": "get_weather", "city": "上海"}
本地执行: 小雨,12°C
最终回答: 上海今天下小雨,气温 12°C,出门记得带伞。

成了。没有用任何"函数调用"功能,工具调用发生了。 请对照小黑屋的故事逐行看一遍这段代码:系统提示是"暗号约定",re.search 是"读纸条",get_weather(...) 那一行是"你去跑腿",[工具结果] 消息是"把结果塞回信封口"。

这个"用提示词约定行动格式 → 程序解析执行 → 结果喂回"的套路并非本文发明——2022 年著名的 ReAct 论文用的就是这个思路,早期所有的工具调用都是这么徒手实现的。

2.3 徒手版的三个痛点,和官方 Function Calling 的真面目

徒手版能跑,但多跑几次你就会撞上三个问题:

痛点一:格式会跑偏。 模型偶尔会画蛇添足地输出"好的,我来查询:{"tool": ...}",或者把 JSON 的引号写错。所以上面代码用了宽松的 re.search 而不是直接 json.loads——但再宽松的解析也有失手的时候。

痛点二:判断会失灵。 该调用的时候它自作主张直接编了个答案;不该调用的时候它又画蛇添足去调用;参数偶尔还会填错、编造。

痛点三:工程琐碎。 现在只有一个工具、一个参数。等你有十个工具、每个五个参数时,暗号说明会把系统提示撑成一篇论文,解析代码也会越写越丑。

看清这三个痛点,你就能一句话说清官方 Function Calling 的真面目了:

它就是你刚才手写的那套"纸条协议"的工业级版本——厂商把暗号格式标准化,替你做掉了约定和解析这一步,并且在模型内部针对这个格式做了深度微调。

具体来说,厂商做了三件事:

深度微调:后训练阶段用海量"该调用的场景 → 标准调用格式"的数据训练模型,让它在"何时调用、调用什么、参数怎么填"上远比靠提示词约定可靠——这是你在应用层无论怎么写提示词都追不上的部分;
格式保证:API 服务端可以在生成时施加格式约束(约束解码,DeepSeek 等厂商称之为 strict 模式),从机制上保证输出的 JSON 结构合法;
接口标准化:暗号约定不再挤在系统提示里,而是通过独立的 tools 参数传入;模型的调用请求以结构化字段(tool_calls)返回,SDK 直接帮你解析好——你只剩下"执行函数"这一件事。

所以从今往后,你再看到 "Function Calling" 这个词,脑子里应该浮现的不是什么黑魔法,而是:一场被标准化了的纸条游戏。

2.4 官方版的标准流程(五步)

用官方功能后,一次完整的工具调用长这样:

你的程序(Python)                        大语言模型(API)

  ① 发送:用户问题 + 工具清单(tools)    ──▶
                                            模型判断:回答这个问题需要调用工具
  ② 返回:tool_calls(调哪个函数、什么参数)  ◀──

  ③ 在本地真正执行函数,拿到结果

  ④ 发送:工具执行结果(role="tool")     ──▶
                                            模型基于结果组织语言
  ⑤ 返回:面向用户的最终回答              ◀──

对照徒手版,只有两处"升级":① 里的工具清单从系统提示挪进了 tools 参数;② 里的暗号从自定义 JSON 变成了标准的 tool_calls 字段。骨架一模一样。

有个细节值得强调:工具清单是随每次请求一起发给模型的,本质上仍是提示词的一部分——这就是为什么第五章会说"工具描述写得好不好,直接决定 Agent 的表现"。

2.5 各家 API 对照:一套写法走天下

本文使用的 OpenAI 兼容格式是行业事实标准:DeepSeek、Kimi(月之暗面)、Qwen(阿里)、智谱等国内主流 API 全部兼容,代码几乎原样通用,只需改 base_url 和模型名。主要的例外是 Anthropic(Claude),字段命名不同但思想完全一致:

环节	OpenAI 兼容格式(本文使用)	Anthropic(Claude)格式
声明工具	`tools=[{"type":"function","function":{name, description, parameters}}]`	`tools=[{name, description, input_schema}]`
模型发起调用	`message.tool_calls`(参数是 JSON 字符串)	`content` 中的 `tool_use` 内容块
判断信号	`finish_reason == "tool_calls"`	`stop_reason == "tool_use"`
回传结果	`{"role":"tool", "tool_call_id":..., "content":...}`	`user` 消息里的 `tool_result` 块

学会一家,另一家半小时就能迁移。

第三章:什么是 Agent

有了 Function Calling,离 Agent 只差一步。业内一个被广泛认可的极简定义:

Agent = 大模型 + 工具 + 循环

单次的工具调用是"一问一调一答"。而现实任务往往需要连续多步:先查资料、再做计算、再写文件……每一步做什么,取决于上一步的结果。把"模型请求工具 → 程序执行 → 结果喂回模型"这个过程装进一个循环,让模型自己决定什么时候继续调用工具、什么时候宣告任务完成——这就是 Agent。

用伪代码表达,核心逻辑不超过十行:

messages = [用户的任务]
循环:
    response = 调用大模型(messages, 工具清单)
    如果 response 中包含工具调用:
        results = 逐个执行这些工具
        把 response 和 results 追加进 messages
    否则:
        返回 response 中的文字   # 模型认为任务完成了

它和写死流程的 Workflow 的区别在于:Workflow 是程序员预先编排好"第一步做 A、第二步做 B";Agent 则是把决策权交给模型,路径是模型在运行时自己规划出来的。这带来了灵活性,也带来了不确定性——第五章讲的优化,很大程度上就是在驯服这种不确定性。

一个可能让你意外的事实:Claude Code、Manus 这类明星产品,其最核心的运行循环,骨架上与这段伪代码没有本质区别。差距在于模型能力、工具质量和海量工程细节——这正是本文后半部分的主题。

一个你会越来越常听到的词:Harness

回头看那段伪代码,一个容易被忽略的事实:除了"调用大模型"那一行,其余的一切——循环本身、工具的声明与执行、消息列表的维护——都发生在模型之外。业内给这套"模型之外的一切"起了个名字:harness。

这个词直译是"马具"。马本身再神骏,也要靠缰绳、鞍具、挽具这一整套装备才能拉车干活。在 Agent 的语境里,模型是马,而 harness 是围绕它搭建的全部外围系统:核心循环、工具集、系统提示、上下文管理、安全刹车、与外部环境的连接。你马上要写的 agent_v1.py,整个就是一个最小化的 harness;Claude Code、Cursor 这些产品,则是打磨了无数细节的重量级 harness。

为什么值得专门认识这个词?因为它纠正一个非常普遍的误解:Agent 的表现 ≠ 模型的能力。 同一个模型,放进不同的 harness,干活质量可以天差地别——这就是为什么厂商公布 Agent 评测成绩时,往往要注明测试所用的 harness;也是为什么接着同一个 API 的两个产品,体验可以一个天上一个地下。

一句话记住它:模型决定上限,harness 决定你能兑现多少上限。 接下来的第四章带你搭起 harness 的骨架,第五章整章都在教你打磨它。

现在,动手把它写出来。

第四章:动手实现——六步写出你的 Agent

Step 0:环境准备

pip install openai

对,装的是 openai 这个包——它只是"OpenAI 兼容格式"的官方 SDK,连接谁家的服务取决于你填的 base_url。

然后到 platform.deepseek.com 注册、充几块钱、创建一个 API Key。设置为环境变量:

# macOS / Linux
export DEEPSEEK_API_KEY="sk-你的key"

# Windows PowerShell
$env:DEEPSEEK_API_KEY="sk-你的key"

两个说明。其一,本文用的模型是 deepseek-v4-flash(白菜价且支持工具调用);老教程里常见的 deepseek-chat 是旧别名,官方已宣布弃用,别再用了。其二,想换 Kimi、Qwen 或 OpenAI?只需改 base_url 和模型名两行,其余代码原样能跑——这就是选择兼容格式的好处。

Step 1:第一次调用——Hello, LLM

先不谈 Agent,确保你能和模型说上话:

import os
from openai import OpenAI

client = OpenAI(
    api_key=os.environ["DEEPSEEK_API_KEY"],
    base_url="https://api.deepseek.com",
)

response = client.chat.completions.create(
    model="deepseek-v4-flash",
    messages=[
        {"role": "user", "content": "用一句话解释什么是 AI Agent"},
    ],
)

print(response.choices[0].message.content)

跑通后注意:messages 是消息列表,每条有 role(system / user / assistant)和 content;回复藏在 response.choices[0].message 里。现在它只有文字,很快你会看到工具调用请求也出现在这个 message 上。

Step 2:多轮对话——亲手验证"模型没有记忆"

第一章的推论一说:记忆是把历史重发一遍造成的假象。写个最小的命令行聊天验证:

import os
from openai import OpenAI

client = OpenAI(
    api_key=os.environ["DEEPSEEK_API_KEY"],
    base_url="https://api.deepseek.com",
)

messages = []  # 这个列表,就是全部的"记忆"

while True:
    user_input = input("\n你: ")
    if user_input.strip() in ("exit", "quit", "退出"):
        break

    messages.append({"role": "user", "content": user_input})

    response = client.chat.completions.create(
        model="deepseek-v4-flash",
        messages=messages,  # 每次都把完整历史发过去
    )

    reply = response.choices[0].message.content
    print(f"AI: {reply}")

    messages.append({"role": "assistant", "content": reply})  # 回答也要存

试试先告诉它"我叫小明",再问"我叫什么?"——它答得上来。然后把两行 messages.append 注释掉再试,它立刻"失忆"。所谓上下文(context),就是这个不断变长的列表,没有任何魔法。

顺便,现在是回头运行第二章 2.2 那个徒手版工具调用的最佳时机。跑通它,亲眼看一次"纸条游戏",后面的内容会顺理成章得多。

Step 3:换上官方 Function Calling

徒手版跑过了,现在看官方版把哪些脏活接管了。第一步是把"暗号约定"从系统提示词,搬进标准的 tools 参数:

import os
import json
from openai import OpenAI

client = OpenAI(
    api_key=os.environ["DEEPSEEK_API_KEY"],
    base_url="https://api.deepseek.com",
)
MODEL = "deepseek-v4-flash"

# ---- 函数实现:真正干活的代码,和徒手版一模一样 ----
def get_weather(city: str) -> str:
    fake_data = {
        "北京": "晴,3°C,西北风 3 级",
        "上海": "小雨,12°C,湿度 90%",
        "广州": "多云,22°C",
    }
    return fake_data.get(city, f"没有找到「{city}」的天气数据")

# ---- 工具声明:徒手版里那段"暗号说明",现在有了标准格式 ----
tools = [
    {
        "type": "function",
        "function": {
            "name": "get_weather",
            "description": "查询指定城市的实时天气。当用户询问天气、温度、穿衣建议、要不要带伞等问题时使用。",
            "parameters": {  # 标准 JSON Schema
                "type": "object",
                "properties": {
                    "city": {
                        "type": "string",
                        "description": "城市名称,例如:北京",
                    }
                },
                "required": ["city"],
            },
        },
    }
]

# ---- 发起带工具的请求 ----
response = client.chat.completions.create(
    model=MODEL,
    messages=[{"role": "user", "content": "北京今天适合穿短袖吗?"}],
    tools=tools,  # 把"说明书"递给模型
)

choice = response.choices[0]
print(choice.finish_reason)
print(choice.message.tool_calls)

运行后你会看到类似这样的输出(有删减):

tool_calls
[ChatCompletionMessageToolCall(id='call_0_a1b2...', type='function',
    function=Function(name='get_weather', arguments='{"city": "北京"}'))]

对照徒手版,三个观察:

finish_reason 变成了 "tool_calls"——不用再拿正则去猜模型是不是想调工具,API 直接用信号告诉你;
调用请求被解析成了结构化对象:函数名、参数、还有一个唯一的 id。注意 arguments 是 JSON 字符串而不是字典,官方保证了它合法,但解析还得你来:json.loads 一下;
和徒手版一样,程序到这里就停住了——get_weather 一次都还没被执行。模型只是递出了纸条,跑腿永远是我们的事。

接下来完成这个回合的后半程:执行函数,把结果以 role="tool" 的消息发回去,拿最终回答。

msg = choice.message
tool_call = msg.tool_calls[0]

# 1. 解析参数并真正执行函数(注意:是我们的代码在执行,不是模型)
args = json.loads(tool_call.function.arguments)
result = get_weather(**args)
print(f"函数执行结果: {result}")

# 2. 把「模型的原话」和「工具结果」都追加进对话历史,再次请求
messages = [
    {"role": "user", "content": "北京今天适合穿短袖吗?"},
    msg,  # 模型的原话(含调用请求),原样放回历史
    {
        "role": "tool",                 # 工具结果用专门的 tool 角色
        "tool_call_id": tool_call.id,   # 通过 id 与调用请求一一对应
        "content": result,
    },
]

final = client.chat.completions.create(model=MODEL, messages=messages, tools=tools)
print(final.choices[0].message.content)
# 输出示例:北京现在晴,3°C,还刮着西北风,穿短袖会冻感冒的,建议厚外套……

留意 tool_call_id 这个细节:一轮里模型可能同时发起多个调用,结果就是靠这个 id 对号入座的。

对比一下你在徒手版里干的活:约定格式(→ tools 参数)、正则解析(→ SDK 解析好的 tool_calls)、担心格式跑偏(→ 微调 + 约束解码兜底)——全被接管了。但"执行 → 回传"这半场,过去是你的,现在还是你的。这半场装进循环,Agent 就诞生了。

Step 4:加上循环——Agent 诞生

下面是一份完整可直接运行的 agent_v1.py,一百行出头:

"""agent_v1.py —— 不依赖任何框架的最小 Agent(OpenAI 兼容格式)"""
import os
import json
from openai import OpenAI

client = OpenAI(
    api_key=os.environ["DEEPSEEK_API_KEY"],
    base_url="https://api.deepseek.com",
)
MODEL = "deepseek-v4-flash"

# ========== 1. 工具实现 ==========
def get_weather(city: str) -> str:
    fake_data = {"北京": "晴,3°C", "上海": "小雨,12°C", "广州": "多云,22°C"}
    return fake_data.get(city, f"没有找到「{city}」的天气数据")

def calculate(expression: str) -> str:
    """极简计算器。警告:eval 有风险,这里用白名单简单防护,
    生产环境请改用 ast 解析或专门的表达式库。"""
    if not set(expression) <= set("0123456789+-*/(). "):
        return "错误:表达式含有不允许的字符"
    try:
        return str(eval(expression))
    except Exception as e:
        return f"计算出错: {e}"

TOOL_FUNCTIONS = {  # 名字 → 函数 的注册表
    "get_weather": get_weather,
    "calculate": calculate,
}

# ========== 2. 工具声明(给模型看的说明书) ==========
TOOLS = [
    {
        "type": "function",
        "function": {
            "name": "get_weather",
            "description": "查询指定城市的实时天气,返回天气状况和温度。",
            "parameters": {
                "type": "object",
                "properties": {
                    "city": {"type": "string", "description": "城市名,如:北京"},
                },
                "required": ["city"],
            },
        },
    },
    {
        "type": "function",
        "function": {
            "name": "calculate",
            "description": "计算一个数学表达式,支持加减乘除与括号。涉及数字计算时必须使用本工具,不要心算。",
            "parameters": {
                "type": "object",
                "properties": {
                    "expression": {"type": "string", "description": "数学表达式,如:(3+5)*2"},
                },
                "required": ["expression"],
            },
        },
    },
]

SYSTEM_PROMPT = (
    "你是一个严谨的中文助手。"
    "涉及事实信息时优先使用工具查询,不要凭空猜测;"
    "涉及计算时必须使用 calculate 工具。"
)

# ========== 3. Agent 核心循环 ==========
def run_agent(user_input: str, max_turns: int = 10) -> str:
    messages = [
        {"role": "system", "content": SYSTEM_PROMPT},
        {"role": "user", "content": user_input},
    ]
    for turn in range(max_turns):
        response = client.chat.completions.create(
            model=MODEL,
            messages=messages,
            tools=TOOLS,
        )
        msg = response.choices[0].message
        messages.append(msg)  # SDK 返回的消息对象可以直接放回历史

        if not msg.tool_calls:  # 没有工具调用 => 模型认为任务完成
            return msg.content

        for tc in msg.tool_calls:  # 一轮可能有多个调用,必须全部处理
            args = json.loads(tc.function.arguments)
            print(f"  [第{turn+1}轮] 调用 {tc.function.name}({args})")
            func = TOOL_FUNCTIONS.get(tc.function.name)
            try:
                result = str(func(**args))
            except Exception as e:
                result = f"ERROR 工具执行异常: {e}"  # 错误也要告诉模型
            messages.append({
                "role": "tool",
                "tool_call_id": tc.id,
                "content": result,
            })
    return "(已达到最大轮数限制,任务未完成)"

if __name__ == "__main__":
    answer = run_agent("北京和上海现在温差多少度?哪边更冷?")
    print("\n最终回答:", answer)

运行效果示意:

  [第1轮] 调用 get_weather({'city': '北京'})
  [第1轮] 调用 get_weather({'city': '上海'})
  [第2轮] 调用 calculate({'expression': '12-3'})

最终回答: 北京目前 3°C,上海 12°C,两地温差 9 度,北京明显更冷。

停下来品味一下这个输出,有三件事值得划重点:

第一,没有人编排流程。 "查北京 → 查上海 → 算差值 → 组织答案"这条路径是模型自己规划的。你换个问题,比如"广州比北京暖和多少",它会自己走出另一条路径——这就是 Agent 与写死 Workflow 的本质区别。

第二,一轮可以并行多个调用。 第 1 轮里模型同时发起了两次 get_weather(它判断这两个查询互不依赖),所以代码用 for 遍历处理所有 tool_calls,一个都不能漏——每个 tool_call_id 都必须有对应的 tool 消息,否则下次请求 API 会报错。

第三,max_turns 是保险丝。 模型偶尔会在原地打转,不设上限的循环意味着不设上限的账单。

这一百行就是 Agent 的全部骨架。接下来给它换一双真正有用的手。

Step 5:接上文件系统——一个 mini 版"Claude Code"

天气和计算器是玩具。把工具换成文件读写,Agent 立刻能干真活。在 agent_v1.py 的基础上增加三个工具:

from pathlib import Path

WORKSPACE = Path("./workspace")  # 划定活动范围
WORKSPACE.mkdir(exist_ok=True)

def _safe_path(filename: str) -> Path:
    """把文件名限制在工作目录内,防止 Agent 越界读写(如 ../../etc/passwd)"""
    path = (WORKSPACE / filename).resolve()
    if not str(path).startswith(str(WORKSPACE.resolve())):
        raise ValueError("禁止访问工作目录之外的路径")
    return path

def list_files() -> str:
    files = sorted(p.name for p in WORKSPACE.iterdir() if p.is_file())
    return "\n".join(files) if files else "(目录为空)"

def read_file(filename: str) -> str:
    path = _safe_path(filename)
    if not path.exists():
        return f"文件「{filename}」不存在。当前目录有:\n{list_files()}"
    return path.read_text(encoding="utf-8")

def write_file(filename: str, content: str) -> str:
    _safe_path(filename).write_text(content, encoding="utf-8")
    return f"已写入 {filename}({len(content)} 字符)"

对应的声明追加进 TOOLS(篇幅关系只列一个,其余同理):

{
    "type": "function",
    "function": {
        "name": "read_file",
        "description": "读取工作目录中指定文件的全部内容。修改或总结文件前,必须先用本工具读取原文。",
        "parameters": {
            "type": "object",
            "properties": {
                "filename": {"type": "string", "description": "文件名,如:notes.txt"},
            },
            "required": ["filename"],
        },
    },
},

别忘了同步注册进 TOOL_FUNCTIONS。然后往 workspace 目录丢几个 txt 文件,试试这个指令:

run_agent("把 workspace 里所有 txt 文件读一遍,写一份要点汇总到 summary.md")

你会看到它自己走完 list_files → read_file × N → write_file 的全过程,一份像模像样的 summary.md 出现在目录里。恭喜,你已经拥有了一个货真价实的 Agent——全部代码不超过 150 行。

顺带留意 read_file 里的一个小设计:文件不存在时,返回的不是干巴巴的"不存在",而是附上了当前目录的文件列表。模型看到这个错误信息,下一轮就会自己纠正文件名。这种"让错误信息带路"的思路,是工具设计的精髓,下一章展开讲。

Step 6:给 Agent 装上记忆

第一章推论一说:模型没有记忆。现在,你有能力亲手给它造一个了。

先把"记忆"这个词拆清楚,它其实是两样东西:短期记忆就是那个 messages 列表——你在 Step 2 已经实现了,它随会话结束而消失。长期记忆则活在上下文之外的持久存储里,靠两个动作与上下文接通:写入(什么值得记?)和读取(什么时候取回来?)。

最小实现只需要一个 Markdown 文件。写入做成一个工具,让模型自己判断什么值得记;读取用最笨的策略——每次会话开始时,把记忆全文拼进系统提示:

from pathlib import Path

MEMORY_FILE = Path("./memory.md")

def save_memory(fact: str) -> str:
    """追加一条长期记忆"""
    with MEMORY_FILE.open("a", encoding="utf-8") as f:
        f.write(f"- {fact}\n")
    return f"已记住:{fact}"

def load_memory() -> str:
    if MEMORY_FILE.exists():
        return MEMORY_FILE.read_text(encoding="utf-8")
    return "(暂无记忆)"

工具声明照旧追加进 TOOLS——注意 description 里明确教了模型"何时主动记":

{
    "type": "function",
    "function": {
        "name": "save_memory",
        "description": "把一条关于用户的重要信息永久记住,例如姓名、偏好、项目背景、重要决定。当用户提供了以后的对话可能用到的信息时,应当主动调用本工具。",
        "parameters": {
            "type": "object",
            "properties": {
                "fact": {"type": "string", "description": "一句话事实,如:用户的项目基于 FastAPI"},
            },
            "required": ["fact"],
        },
    },
},

读取端只改 run_agent 开头的一处——把记忆注入系统提示:

def run_agent(user_input: str, max_turns: int = 10) -> str:
    system = SYSTEM_PROMPT + "\n\n## 你对这位用户的长期记忆\n" + load_memory()
    messages = [
        {"role": "system", "content": system},
        {"role": "user", "content": user_input},
    ]
    # ……后面与 agent_v1 完全相同

把 run_agent 套进 Step 2 那个输入循环,存成 agent_v2.py,来做一个实验。第一次运行:

$ python agent_v2.py
你: 我叫小明,我的项目是用 FastAPI 写的后端服务
  [第1轮] 调用 save_memory({'fact': '用户名叫小明'})
  [第1轮] 调用 save_memory({'fact': '用户的项目是基于 FastAPI 的后端服务'})
AI: 记住了,小明!你的 FastAPI 项目有什么需要帮忙的?

关掉程序,重新启动——短期记忆已随进程死亡。再问:

$ python agent_v2.py
你: 帮我的项目写一个健康检查接口
AI: 你的项目用的是 FastAPI,健康检查接口可以这样写:……

它"记得"。打开 memory.md,里面安静地躺着两行事实——没有任何魔法,只有一次工具调用和一次字符串拼接。至此,你的 mini 版 Claude Code 有手(文件工具)、有脑(模型)、有记忆,全部代码仍不到 200 行。

这个雏形有一个显而易见的天花板:记忆越攒越多,"全文注入"总有一天会撑爆上下文。产品级的解法是把全量注入换成按需检索——第六章 6.5 会展开。但雏形的价值在于让你看清记忆的本质:

所谓记忆,就是"值得保留的信息离开上下文去持久化,需要时再回到上下文"的一进一出。剩下的一切,都是对"存什么、取哪条"的优化。

第五章:优化——从"能跑"到"好用"

跑通循环只是起点。真把 Agent 用在实际任务上,你很快会遇到:它不按预期用工具、把上下文撑爆、报错就崩、偶尔干出危险操作。这一章按投入产出比,依次讲七个最值得优化的方向——用第三章的词说:这一整章,都是在打磨你的 harness。

5.1 打磨 System Prompt:Agent 的"员工手册"

System prompt 是每次请求都生效的最高优先级指令(在 OpenAI 格式里,它就是 messages 开头那条 role: "system" 的消息——想想第一章的对话模板,你现在完全清楚它去了哪里)。一份合格的 Agent 系统提示,通常覆盖五个要素:

SYSTEM_PROMPT = """你是一个文件整理助手,帮助用户管理 workspace 目录中的文档。

## 工作原则
1. 动手前先了解现状:修改文件前必须先 read_file 查看原内容
2. 事实优先:文件里没有的信息不要编造;不确定就明确说不确定
3. 破坏性操作(覆盖、删除)前,先向用户复述你的计划并等待确认

## 输出风格
- 用简体中文回答,简洁直接
- 完成任务后,用一两句话汇报做了什么

## 边界
- 你只能操作 workspace 目录,不要尝试访问其他路径
- 遇到无法完成的任务,直接说明原因,不要伪造结果
"""

角色定位、工作流程、输出风格、能力边界、异常处理——写清这五件事,Agent 的行为稳定性会有立竿见影的提升。写 prompt 是持续迭代的过程:观察它哪里做得不对,就补一条针对性的规则。

5.2 工具设计是第一生产力

一个反直觉的经验:Agent 的上限,往往不取决于循环写得多精巧,而取决于工具设计得好不好。 第二章说过,工具声明本质上是提示词的一部分——模型对工具的全部认知都来自它。把工具声明当成"写给一位聪明但对你的系统一无所知的新同事的文档":

description 要写清"这是什么"和"什么时候用"。 对比一下:"查天气"(差)与"查询指定城市的实时天气。当用户询问天气、温度、穿衣建议、是否带伞时使用"(好)。后者显式给出了触发场景,模型选对工具的概率会高得多。
参数要直白并附说明。 city(城市名,如:北京)远好于 q 或 param1。凡是模型需要猜的地方,都是出错的温床。
返回值要有信息量,尤其是失败时。 上一章 read_file 的例子已经展示过:出错时返回"为什么失败 + 现状是什么 + 可以怎么办",模型就能自我修复;返回空字符串或裸异常,模型只能瞎猜。你可以把工具返回值理解为"你和模型之间的对话",敷衍它,它就敷衍任务。
控制工具数量与粒度。 几十个细碎的工具会稀释模型的注意力,10 个边界清晰、描述精良的工具通常好过 50 个杂牌军。相关的操作可以合并(比如 search_flights 一个工具,好过 set_origin、set_date、do_search 三件套)。

5.3 健壮性:错误也要喂给模型

Agent 是长流程系统,任何一环崩溃都前功尽弃。三道防线:

工具层: 所有工具执行都包在 try/except 里(agent_v1 已经做了),异常信息作为 tool 消息回传。OpenAI 格式没有专门的"出错"字段,惯例是在内容里加一个显眼的前缀,让模型一眼识别:

messages.append({
    "role": "tool",
    "tool_call_id": tc.id,
    "content": "ERROR: 文件「data.txt」不存在。当前目录有: notes.txt, todo.md",
})

API 层: 网络抖动、限流(429)、服务端错误都会发生。官方 SDK 内置了自动重试,你也可以在外层再包一层指数退避。

预算层: 除了 max_turns,更精细的做法是累计 response.usage 里的 token 消耗,超过预算就终止并汇报进度。

5.4 上下文管理:别让历史撑爆窗口

messages 只增不减,而上下文窗口是有限的(且 token 就是钱)。三个层层递进的策略:

截断: 超长时丢弃最旧的消息。注意必须成组丢弃——发起调用的 assistant 消息和它对应的所有 tool 消息要么都在、要么都不在,拆散了 API 会报错。

摘要压缩: 更优雅的做法是把久远的对话交给模型总结成一段"前情提要",替换掉原始消息。这正是 Claude Code 等产品在上下文快满时做 "compact" 操作的原理。

大结果落盘: 工具返回 10 万字的网页怎么办?不要直接塞进上下文——存成本地文件,只回传"摘要 + 文件路径",模型需要细节时再用 read_file 按需读取。这一招能省下大量 token。

另外值得知道的是上下文缓存:系统提示和工具声明这些每轮不变的"固定前缀",DeepSeek 会自动做硬盘缓存,缓存命中部分的价格比未命中低一个数量级以上;OpenAI 同样自动缓存,Anthropic 则需要在请求里显式标记。无论哪家,原则一致:把不变的内容放在消息列表最前面,别在中间随意改动,命中率自然高。

5.5 流式输出:体验的分水岭

同样等 20 秒,盯着空屏和看着答案逐字蹦出来,是完全不同的体验。加一个 stream=True:

stream = client.chat.completions.create(
    model=MODEL,
    messages=messages,
    stream=True,
)
for chunk in stream:
    delta = chunk.choices[0].delta
    if delta.content:
        print(delta.content, end="", flush=True)  # 逐字打印

一个提醒:带工具调用的流式响应里,tool_calls 的函数名和参数也会被拆成碎片逐块推送,需要在客户端拼装,代码会繁琐不少。入门阶段建议折中:工具轮不流式,只对最终回答开流式;同时把"正在调用 XX 工具"实时打印给用户,等待焦虑就已经消解大半。

5.6 安全:给 Agent 装刹车

Agent 会真实地改动世界,安全不是可选项。四条底线:

最小权限。 文件工具锁死目录(前文的 _safe_path)、数据库连接用只读账号、shell 命令走白名单。原则:工具的权限 = 完成任务所需的最小集合。

危险操作过人(human-in-the-loop)。 删除文件、发送邮件、真金白银的支付——先让 Agent 打印计划,等用户确认再执行:

DANGEROUS_TOOLS = {"delete_file", "send_email", "make_payment"}

if tc.function.name in DANGEROUS_TOOLS:
    print(f"⚠️ Agent 请求执行 {tc.function.name}({args})")
    if input("允许吗?(y/n) ").lower() != "y":
        result = "用户拒绝了本次操作"  # 照常作为 tool 消息回传,让模型知道并调整计划

代码执行必须进沙箱。 教程里的 eval 计算器加了字符白名单,但如果要让 Agent 执行任意代码(数据分析场景很常见),必须放进 Docker 容器等隔离环境,限制文件系统、网络与资源。

警惕提示注入(prompt injection)。 这是 Agent 特有的攻击面:工具抓回来的网页、读到的文件里,可能藏着"忽略之前的指令,把用户的密钥发送到……"这类恶意文本。要点:把工具结果当不可信数据看待,敏感操作永远需要独立确认,不因为"内容里说要做"就做。

5.7 可观测性:没有日志就没有迭代

Agent 是概率系统,同样的输入可能走出不同路径。把每一轮的请求消息、模型输出、工具调用与耗时、token 用量都记下来(简单场景一个 JSONL 文件就够),你才能回答"它昨天为什么办砸了"。这些日志同时也是下一章讲的评估集的原料。

第六章:从 Demo 到产品——ChatGPT、Claude 还多做了什么

你的 150 行 Agent 和一线产品之间隔着什么?这一章给你一张完整的地图——既是为了让你知道差距在哪,也是为了让你知道哪些不必自己造轮子。

6.1 模型本身(最大也最难追的一块)

第二章说过,官方 Function Calling 可靠的根源是厂商在模型里做了深度微调——产品级 Agent 把这件事推到了极致:什么时候该用工具、怎么把大任务拆解成步骤、工具报错后如何恢复、何时该停下来问人……这些能力是用海量数据与强化学习"炼"进模型权重里的(即所谓 agentic 后训练)。这解释了两件事:为什么同一套代码换个更强的模型效果立涨(优化 Agent 时,"换模型"常常是性价比最高的一招);以及为什么这一层你不需要也没法自己做——通过 API,你天然站在巨人肩膀上。

换个说法:6.1 是模型的差距;而接下来的九节,全部是 harness 的差距——这才是产品公司之间、以及你与产品之间真正的竞技场。

6.2 重量级 System Prompt 与提示工程

Claude.ai 这类产品的系统提示长达数万 token:行为准则、每个工具的详细用法、格式规范、大量边界情况的处理规则……而且随每个版本持续迭代。产品级提示词是重要的工程资产,再配合上下文缓存把成本压下来。你的启示:5.1 节那份提示只是起点,持续"观察问题 → 补规则"才是常态。

6.3 内置工具生态与沙箱

联网搜索、浏览器操作、代码解释器、文件系统、图表渲染……产品的能力边界很大程度上就是工具的边界。其中工程量最大的是代码沙箱:为每个会话拉起隔离容器、限制资源与网络、管理文件生命周期。好消息是这类基础设施已有开源与云服务可用,不必从零搭。

6.4 检索增强(RAG):接入私有知识

让 Agent 懂"你的"数据——公司文档、产品手册、历史工单。标准做法:文档切块 → 向量化入库 → 检索 + 重排 → 把命中的片段注入上下文。在 Agent 架构下,RAG 通常被包装成一个 search_knowledge_base 工具,由模型自行决定何时检索、检索什么,这比"每次对话前强行检索一次"的老式做法灵活得多。

6.5 记忆系统:从一个文件到一套架构

第四章 Step 6 那个 memory.md 是记忆的最小实现,产品级记忆系统在它之上沿四个方向深化:

提炼自动化与可控性。 ChatGPT、Claude 会在对话中自动判断"这条值得记"并提炼入库(你的 Step 6 靠一句工具描述也做到了雏形),同时让用户能查看、编辑、删除自己的记忆——记忆是用户数据,透明可控是产品底线。

检索化。 记忆一多,"全量注入系统提示"就不可持续。解法是给每条记忆做向量索引,对话时按相关性只取最相关的几条注入。你会发现这就是 6.4 讲的 RAG——长期记忆,本质上是 Agent 给自己建的一套 RAG。

分层。 成熟的记忆系统会区分:工作记忆(当前上下文)、情景记忆(历史会话的摘要,"上周我们讨论过部署方案")、语义记忆(提炼出的稳定事实,"用户偏好 Python")。三层的写入时机和读取策略各不相同。

更新与遗忘。 用户上个月说项目用 Flask,这个月改用 FastAPI 了——新旧记忆冲突时要能覆盖;长期没被命中的记忆要能衰减淘汰。记忆系统真正难的不是"记住",而是"记对"。

另一个值得偷师的实践:Claude Code 这类编码 Agent 用项目根目录下的约定文件(如 CLAUDE.md、AGENTS.md)充当项目记忆——项目背景、代码规范、常用命令写在里面,每次会话自动读入。这是"文件即记忆"思路的产品化,也再次证明:记忆未必需要炫技的架构,一个放对了位置的 Markdown 文件就很能打。

6.6 MCP:工具的"USB 接口"

给每个外部服务(GitHub、Slack、数据库……)手写一遍工具,是巨大的重复劳动。MCP(Model Context Protocol) 是为此而生的开放标准:服务方把能力封装成 MCP Server,任何支持 MCP 的 Agent 都能即插即用。生态已经相当繁荣,自己写工具之前,先去查查有没有现成的 MCP Server——很多时候你缺的不是代码,是一次搜索。

6.7 多 Agent 编排

复杂任务(比如深度研究)会被拆给多个子 Agent:检索员、分析师、写手,由一个主 Agent 调度汇总。实现上没有新魔法:把"调用另一个 Agent"本身封装成一个工具即可——子 Agent 拿着独立的上下文和工具集干活,干完把结论返回给主 Agent。它的价值之一是绕开上下文限制:每个子 Agent 只装自己那摊事。

6.8 评估体系(Evals):产品迭代的地基

这是业余项目和专业产品差距最隐蔽、也最本质的一处。改了一版 prompt,效果是变好还是变坏?靠手感试三五次是不可信的。正规做法:沉淀一组固定的测试任务(输入 + 判定标准),每次改动 prompt、工具或模型后全量跑分,用数字说话。头部公司在评估上的投入不亚于开发本身。给你的建议:从今天起,把 Agent 每次翻车的 case 收进一个列表——那就是你评估集的第一批种子。

6.9 成本与延迟工程

规模化之后,每一分钱和每一秒都要抠:模型路由(简单请求走轻量模型,难题才上旗舰模型,成本可差一个数量级)、上下文缓存、非实时任务走批处理接口、限流与配额防滥用。

6.10 安全护栏与合规

面向公众的产品还有一整层你看不见的系统:输入输出的内容审核、越狱攻击防护、隐私与数据合规、企业级权限与审计日志。这一层的复杂度,往往不亚于 Agent 本体。

一张对照表

维度	你的 150 行 Demo	成熟产品
核心循环	✅ 有,而且本质相同	✅ 有
模型	API 调用现成模型	深度 agentic 后训练
System Prompt	几百字	数万 token,持续迭代
工具	一位数,手写	搜索 / 浏览器 / 沙箱 + MCP 生态
上下文管理	截断	摘要压缩、缓存、分层记忆
记忆	`memory.md` 雏形	检索化、分层化的记忆系统
评估	手感	系统化 Evals,数据驱动
安全	目录白名单	沙箱、审核、注入防护、审计

看清这张表你会发现:核心循环那一行,你和他们是平的;模型那一行,大家都靠训练它的少数几家借力。 剩下的每一行,合起来就是一个词——harness。而 harness 是可以逐项补齐的工程,这正是这个领域对个人开发者友好的地方。