引言

前11篇讲的都是"别人怎么造的"。这一篇换个视角：你自己怎么造一个。

好消息是，项目里的每一个阶段（s01 到 s_full）都是可以直接跑的独立脚本。你不需要读完全部代码才能动手——实际上，从 s01 开始跑起来只需要5分钟。

这篇文章面向想动手的人。如果你是技术人员，跟着步骤操作就行。如果你不写代码，看思路也有价值——你会知道一个 Agent 从无到有需要回答哪些问题。

环境准备

第一步：获取 API Key

你需要一个能调用大语言模型的 API Key。两个选择：

Anthropic 官方：去 console.anthropic.com 注册，创建 API Key。支持 Claude 系列模型。
兼容的第三方服务：如果你在国内，部分平台提供了兼容 Anthropic SDK 的接口（通过设置 ANTHROPIC_BASE_URL）。

第二步：克隆项目 & 安装依赖

git clone https://github.com/anthropics/learn-claude-code.git
cd learn-claude-code
pip install -r requirements.txt

依赖很少，核心就是 anthropic SDK 和 python-dotenv。

第三步：配置环境变量

在项目根目录创建 .env 文件：

ANTHROPIC_API_KEY=your-api-key-here
MODEL_ID=claude-sonnet-4-20250514

如果你用第三方服务，还需要加一行：

ANTHROPIC_BASE_URL=https://your-provider.com/v1

配完这三步，就可以开始了。

五步走：从最简单到完整

Step 1：跑 s01 —— 最简 Agent

python agents/s01_agent_loop.py

输入一个问题，比如"查看当前目录下有什么文件"。你会看到 Agent 自动调用了 bash 工具执行 ls，然后把结果告诉你。

s01 只有一个工具（bash）和一个循环（Agent Loop）。但它已经是一个能干活的 Agent 了。

此时你的 Agent 能做的事：执行任意 shell 命令，包括编译、运行测试、查看日志等。

它不能做的事：直接读写文件内容（只能通过 bash 间接操作）、做计划、管理任务。

Step 2：跑 s02 —— 加上文件操作

python agents/s02_tool_use.py

s02 在 s01 的基础上加了三个工具：read_file、write_file、edit_file。

试试让它"读取 README.md 的内容"或者"创建一个 hello.py 文件"。你会发现 Agent 能直接操作文件了，不需要绕道 bash。

为什么要单独做文件工具，而不是让 bash 工具搞定一切？因为专用工具比通用工具更安全、更可控。write_file 工具会检查路径是否合法（不能写到项目目录之外），而 bash 里的 echo > /etc/passwd 就需要额外的安全拦截逻辑。

核心收获：工具设计的本质是给模型正确的抓手。你希望模型做什么操作，就提供什么工具。

Step 3：跑 s03 —— 加上计划能力

python agents/s03_todo_write.py

给 Agent 一个稍微复杂的任务，比如"帮我创建一个 Python 项目的基本结构，包括 src 目录、tests 目录、setup.py 和 README.md"。

你会看到 Agent 先调用 TodoWrite 列出一个待办清单，然后一项一项地完成。每完成一项，状态会从 [ ] 变成 [x]。

这个变化看起来小，但意义很大。有了计划能力，Agent 能处理多步骤任务，而不是走一步看一步。

Step 4：跑 s05 —— 加上技能加载

python agents/s05_skill_loading.py

s05 引入了"技能"概念。skills/ 目录下的每个 SKILL.md 文件就是一项技能。模型一开始只知道有哪些技能可用（名称 + 一句话描述），需要的时候调用 load_skill 加载具体内容。

你可以自己写一个技能文件试试。比如在 skills/my-api/SKILL.md 里写上你们公司内部 API 的使用指南，Agent 就能按需获取这些知识。

核心收获：技能加载是一种让 Agent 动态获取专业知识的机制，而不是把所有知识都塞进系统提示里。

Step 5：按需选择后续阶段

到 s05 为止，你已经有了一个相当实用的 Agent：能执行命令、读写文件、做计划、按需获取知识。

大多数实际场景，s01 + s02 + 也许 s05 就够了。

后面的阶段解决的是更高级的问题：

需求	选择
Agent 对话太长，上下文爆了	加 s06（上下文压缩）
需要管理多个并行任务	加 s07（任务系统）
有些命令跑很久，不想阻塞	加 s08（后台执行）
需要多个 Agent 协作	加 s09-s12（团队、协议、自治、隔离）

不要过度工程化。如果你的场景是"帮我分析这段代码"，s01 就够了。如果是"帮我重构整个项目"，可能需要 s03 + s06。如果是"三个 Agent 同时开发三个功能"，那才需要 s09-s12。

为你的业务场景设计 Harness

知道怎么跑现成的代码之后，更重要的问题是：怎么为你自己的业务设计 Agent？

这归结为三个问题。

第一步：你的 Agent 需要"摸到"什么？

这是工具设计的问题。

如果 Agent 要操作数据库，给它一个 query_db 工具
如果 Agent 要发邮件，给它一个 send_email 工具
如果 Agent 要调用你们的内部 API，给它一个 call_api 工具

工具设计的原则：一个工具做一件事，输入输出清晰。不要搞一个万能工具接受"请求类型"参数然后内部做 switch——那样模型很难学会正确使用。

看看 s02 里的工具定义：

{"name": "read_file", "description": "Read file contents.",
 "input_schema": {"type": "object",
   "properties": {"path": {"type": "string"}},
   "required": ["path"]}}

名字直白，描述简洁，参数明确。模型一看就知道这个工具干什么、怎么用。

第二步：你的 Agent 需要"知道"什么？

这是知识准备的问题。

系统提示里写的是"角色定义"和"行为准则"。技能文件里放的是"领域知识"。两者不要混淆。

比如你在做一个客服 Agent：

系统提示："你是 XX 公司的客服代表，礼貌、专业，遇到无法解决的问题转人工。"
技能文件：退款政策、产品规格表、常见问题 FAQ

系统提示每次都会发给模型，所以要精简。技能文件按需加载，所以可以详细。

第三步：你的 Agent 不能做什么？

这是权限边界的问题，也是最容易被忽略的。

bash 工具要拦截危险命令（rm -rf /、sudo 等）
文件操作要限定在工作目录内（路径检查）
数据库操作最好只给 SELECT 权限，除非你真的需要它改数据
敏感操作（发邮件、转账）可以设计成"先提交方案，人工审批后再执行"

s10 里的计划审批协议就是一个很好的参考：模型提交计划，人类（或 Lead Agent）审批后才能执行。

记住：你信任模型的智能，但不信任它的安全意识。安全边界必须由 Harness（代码）来保证，不能指望模型"知道"不该做什么。

一个最小可行 Agent 的模板

如果你想从零开始写，下面是最精简的结构。不到30行就能跑：

from anthropic import Anthropic

client = Anthropic()
tools = [
    {"name": "your_tool", "description": "做你需要做的事",
     "input_schema": {"type": "object",
       "properties": {"param": {"type": "string"}},
       "required": ["param"]}}
]

def execute(name, args):
    if name == "your_tool":
        return do_something(args["param"])
    return "Unknown tool"

messages = [{"role": "user", "content": "你的任务描述"}]
while True:
    response = client.messages.create(
        model="claude-sonnet-4-20250514",
        messages=messages, tools=tools, max_tokens=4096)
    messages.append({"role": "assistant", "content": response.content})
    if response.stop_reason != "tool_use":
        break
    results = []
    for block in response.content:
        if block.type == "tool_use":
            output = execute(block.name, block.input)
            results.append({"type": "tool_result",
                           "tool_use_id": block.id,
                           "content": str(output)})
    messages.append({"role": "user", "content": results})

就这么多。一个 while 循环 + 工具执行 = 一个 Agent。

然后根据需要，逐步加上：文件操作（s02）、计划管理（s03）、技能加载（s05）……每次只加你真正需要的东西。

常见误区

"我应该一步到位用 s_full"

不要。s_full 有23个工具和500行代码，绝大多数场景用不到。从 s01 开始，按需叠加。

"我的工具描述写得越详细越好"

不一定。模型对简短清晰的描述理解得最好。写一句话比写一段话更有效。如果真需要详细说明，放到技能文件里按需加载。

"我要把所有知识都塞进系统提示"

千万别。系统提示每次请求都会发送，每个 token 都是钱。把稳定的、精简的指令放系统提示，把详细的、按需的知识放技能文件。

"Agent 能做所有事，不需要人类介入"

现阶段的 Agent 在明确规则的任务上表现出色，但在需要价值判断、利益权衡、社会常识的场景下，仍然需要人类把关。用好审批协议，关键决策留给人。

小结

造一个 Agent 的门槛比你想象的低。一个 API Key + 一个 while 循环 + 一两个工具，就是一个能干活的 Agent。

复杂度不来自框架本身，而来自你对业务场景的理解——你的 Agent 需要什么工具、什么知识、什么边界。这些问题想清楚了，代码实现反而是最快的部分。

项目里的所有代码都可以直接 git clone 下来跑。建议从 s01 开始，每个阶段跑一遍，亲手感受机制叠加的过程。读十遍不如跑一遍。

下一篇是这个系列的最后一篇，我们跳出技术细节，聊聊 Agent 时代对不同角色的人意味着什么。

动手造你自己的 Agent —— 从0到1实操指南

评论区

需要帮助？