译者按: 本文是 Thorsten Ball 于 2025-04-15 发表的《How to Build an Agent (or: The Emperor Has No Clothes)》的中文校对翻译。原文出处: https://ampcode.com/how-to-build-an-agent。读原文时深受启发, 特将全文译出与中文读者分享, 感谢原作者的点醒与提携。译文仅供学习交流, 版权归原作者所有, 如有出入以原文为准。
说明: 原文是一篇约 4000 词的教程长文, 一半以上篇幅是逐步演进的 Go 代码。本文为精译编译版: 完整还原论点、教程步骤与结论, 用编者中文重述; 代码部分只描述其功能与规模, 不逐行搬运 (请直接看原文获取可运行代码)。原文链接见 frontmatter。
一、开篇: 一个大家不敢信的事实
Ball 开篇抛出全文的核心断言: 一个能编辑代码的 AI agent, 没有任何深不可测的秘密。做出一个功能完整、令人震惊地好用的代码编辑 agent, 只需要大约 300 行代码, 其中大部分还是样板代码。
他说这话的语气带着「终于有人把话挑明」的意味: 过去几个月人人都在谈论 agent, 仿佛那是只有大厂才能掌握的黑魔法。他的回答浓缩成一句被疯传的话 (直译): 「没有什么秘密。就是一个 LLM, 一个循环, 加上足够的 token。」其余的都是「过硬的工程活」: 好的提示词、处理边角情况、围绕模型能力设计体验。但核心机制小到你可以在午休时间写完。
于是这篇文章就是带你在午休时间写完它: 用 Go 和 Anthropic API, 从零到一个能读文件、列目录、改代码的 agent。
二、准备工作
环境要求极简: 装好 Go, 有一个 Anthropic API key, 新建一个项目目录。他强调跟着敲一遍的重要性: 光看是不会信的, 亲手跑起来才会有「就这?」的顿悟时刻。
三、第一步: 一个会说话的壳 (对话循环)
先写一个最普通的聊天程序: 读取终端输入, 发给 Claude, 打印回复, 循环。这一步的代码量不足百行, 功能上和网页版聊天没有区别。关键设计只有一个: 维护一个不断追加的消息列表, 让模型每轮都能看到完整对话历史。
四、第二步: 给它第一个工具 (read_file)
接下来是全文的概念核心: 什么叫工具 (tool)?
Ball 的解释刻意平淡: 所谓「给模型一个工具」, 就是在发给它的请求里附上一段说明: 「你可以让我帮你执行这些操作, 想用的时候按这个格式说」。模型想用工具时, 会在回复里输出一个结构化请求; 你的代码解析它, 真的去执行 (比如读文件), 把结果塞回对话, 再让模型继续。
也就是说, 工具调用的本质是: 模型说「请帮我读一下 main.go」, 你的程序照做并把内容贴回去。没有魔法, 没有沙箱里的小人, 只是一场格式化的传话游戏。
他定义了第一个工具 read_file: 名字、一句话描述、一个 JSON 参数格式 (文件路径), 加上真正执行读取的十几行 Go 函数。挂上这个工具后, 对话立刻起了质变: 你问「jokes.txt 里写了什么」, 模型自己决定调用 read_file, 拿到内容后回答你。没有人教它什么时候用工具, 它自己会判断。Ball 提醒读者注意这个细节: 这些模型对使用工具有近乎急切的主动性, 因为工具使用的模式已经在训练中刻进了它的本能。
五、第三步: 第二个工具 (list_files)
同样的配方: 名字、描述、参数格式、执行函数。list_files 让 agent 能看到目录结构。现在它可以自己组合两个工具: 先列目录找到感兴趣的文件, 再读取内容, 多步连续调用, 中间不需要人指挥。Ball 指出这就是「agentic」的全部含义: 模型在循环里自主决定下一步动作, 直到任务完成。
六、第四步: 让它能改世界 (edit_file)
最后一个工具 edit_file 用最简单粗暴的实现: 字符串替换式改文件 (找到旧文本, 换成新文本; 文件不存在就创建)。他承认这个实现在工程上很傻, 但重点是演示: 就算这么傻的编辑工具, 模型也能用它完成真实的编程任务。
装上第三个工具后, 见证时刻到来: 让它「写一个 FizzBuzz 的 JavaScript 脚本」, 它创建文件、写好代码; 让它「改成只输出到 15」, 它读文件、定位、修改; 让它写一个 ROT13 解码脚本, 它一次成型。一个不到 400 行的 Go 程序, 表现出了和商业编程助手同源的核心能力。
七、结论: 皇帝没穿衣服
收尾回到标题的寓言: 大家都以为 agent 背后藏着复杂的系统工程, 其实核心循环简单得让人不好意思。他的结论分两层:
- 能力在模型里, 不在壳里。300 行代码 + 三个工具, 你就在和一个能改你代码的智能对话了。这就是「没有护城河」的含义: 壳人人能写。
- 但产品化仍然是真功夫。他没有说商业工具没价值, 提示词工程、上下文管理、编辑可靠性、用户体验, 这些是把 demo 变成产品的部分 (他本人正是在 Sourcegraph 做 Amp 这个产品)。祛魅的对象是「核心机制」, 不是「产品打磨」。
最后他催促读者: 别光读, 去写。亲手写一遍, 你对整个 AI 编程浪潮的判断力会立刻上一个台阶。
原始来源
- 原文 (含全部可运行代码): https://ampcode.com/how-to-build-an-agent
- 作者宣发推文: https://x.com/thorstenball/status/1912178069336396186
原文出处: How to Build an Agent (or: The Emperor Has No Clothes) 原作者: Thorsten Ball 原文发表: 2025-04-15
本文收录于「X深度阅读」栏目: 精选全球 X/Twitter 与博客上最值得精读的 AI 长文, 逐篇校对翻译成中文。