第 11 章 · 親手打造你的 Agent：20 行做出迷你 Claude Code

到了收成的時刻。前面十章像是在準備食材，這一章我們開火。你會親手寫出一個會自己讀檔、跑指令、修 code 的 AI Agent——然後親眼發現一件事：

一個 AI Agent 的核心，其實只是「一個 while 迴圈 + 會呼叫工具的 LLM」。 Claude Code、Cursor、Aider 全都是從這個 20 行的核心長出來的。

差別只在工具多寡、權限控管與 context 管理的成熟度——也就是第 9 章的 harness。

💡 這一章需要一點 Python 基礎。看不懂程式也沒關係，重點是理解那條「迴圈」——那是整門課的最終拼圖。

學習階梯：從 20 行到 Claude Code

我們用一道階梯，把前面每一章串成一個能跑的成品：

核心就是這段（真的能跑）

下面這段 Python，就是一個能讀檔、能跑指令的迷你 coding agent。看懂它，你就看懂了所有 agent：

import anthropic, subprocess
client = anthropic.Anthropic()

# 1) 你的工具：給兩個，就足以成為「迷你 Claude Code」
tools = [
  {"name": "read_file", "description": "讀取檔案內容",
   "input_schema": {"type": "object",
     "properties": {"path": {"type": "string"}}, "required": ["path"]}},
  {"name": "run_bash", "description": "執行 shell 指令",
   "input_schema": {"type": "object",
     "properties": {"cmd": {"type": "string"}}, "required": ["cmd"]}},
]

def execute(name, args):        # ← 權限、沙箱、審批全都在這一層（這就是「harness」）
    if name == "read_file":
        return open(args["path"]).read()
    if name == "run_bash":
        return subprocess.run(args["cmd"], shell=True,
                              capture_output=True, text=True).stdout

# 2) Agent 的核心：就是這個 while 迴圈
messages = [{"role": "user", "content": "把 app.py 裡的 bug 修好"}]
while True:
    resp = client.messages.create(
        model="claude-opus-4-8", max_tokens=4096,
        tools=tools, messages=messages)

    if resp.stop_reason != "tool_use":          # 模型說「做完了」→ 跳出迴圈
        break

    messages.append({"role": "assistant", "content": resp.content})
    results = []
    for b in resp.content:
        if b.type == "tool_use":                # 模型「請求」用工具
            results.append({"type": "tool_result", "tool_use_id": b.id,
                            "content": execute(b.name, b.input)})
    messages.append({"role": "user", "content": results})   # 把結果餵回去，繼續迴圈

print(resp.content[-1].text)

這 20 行裡藏著整門課：

• tools 的定義 → 第 4 章的工具呼叫；
• 那個 while → 第 7 章的 agentic loop；
• execute() 那層 → 第 9 章的 harness（權限、沙箱都加在這裡）；
• 模型只回傳 tool_use「請求」、真正執行的是你 → 第 4 章那條主線。

圖解：那條迴圈就是 agent 的全部

flowchart LR
    U[使用者請求] --> M[LLM 推理與決策]
    M -->|end_turn 完成| D((回覆使用者))
    M -->|tool_use 要用工具| T[執行工具<br/>read/bash]
    T --> O[觀察結果]
    O -->|tool_result 回饋| M

模型每一輪只做一個決定：「我要用工具，還是我做完了？」 要用工具就執行、把結果餵回、再問一次；直到它說「做完了」（end_turn）才跳出。這條 tool_use → 執行 → tool_result → 再問 的迴圈，就是把「一次性問答的 LLM」變成「會自己動手的 agent」的全部祕密。

三條路：從手刻到 Claude Code 等級

手刻懂了本質之後，真實開發你不需要重造輪子。由淺到深有三條路：

B｜省掉樣板：官方 SDK 的 tool runner 能連 while 都不用寫；或用通用框架 LangGraph、Pydantic AI、OpenAI Agents SDK、smolagents。

C｜繼承整個 harness（第 9 章），三種做法：

1. Claude Agent SDK——就是驅動 Claude Code 的那個 SDK（TypeScript／Python）。直接給你 agentic loop、檔案/bash 工具、權限審批、context 自動壓縮、subagent、MCP。你只補 prompt 跟自己的工具。
2. Anthropic Managed Agents——Anthropic 幫你跑迴圈並代管沙箱；內建工具組就是 bash / read / write / edit / glob / grep（幾乎就是 Claude Code 的工具），你連伺服器都不用顧。
3. 魔改開源 agent——直接 fork Claude Code、Aider、OpenHands 來改。

💡 這一章最重要的一句話：你不需要從零重造 harness。手刻一次是為了「懂」，之後站在 SDK 上，把力氣花在你的工具、你的 prompt、你的 eval（第 10 章）。

動手練習（建議照順序做一次）

1. 把上面那段跑起來，先只給 read_file 一個工具，叫它「讀 app.py 並解釋這支程式在做什麼」。
2. 加上 run_bash，叫它「跑測試看看有沒有過」——觀察它如何自己決定「先讀檔、再跑測試」。
3. 在 execute() 裡加一個審批關卡：run_bash 執行前先 input("要執行嗎？") 問你（這就是 human-in-the-loop，第 7 章）。
4. 換成 Claude Agent SDK 重做一次，體會「同一件事，harness 幫你省了多少」。
5. 用第 10 章的方法，準備 3 個測試任務，評估你的 agent 成功率。

課程總結：你走過的路

恭喜你走到終點。回頭看，這 11 章其實是一條完整的弧線：

• 懂原理（1–4）：模型是「猜下一個字」→ 怎麼跟它講話（prompt）→ 怎麼管它的記憶（context）→ 怎麼讓它動手（工具）。
• 接系統與資料（5–6）：用工作流把它串成流水線 → 用 RAG 餵它你的知識。
• 理解自主代理（7–9）：agent 就是「會用工具的迴圈」→ 用 MCP 標準接工具 → 用 harness 包成能跑、可控、安全的成品。
• 會評估與防護（10）：用評估、追蹤、護欄、成本控制，讓它敢上線。
• 親手做出來（11）：把以上全部，收束成一個 20 行的 while 迴圈。

你現在不只「會用 AI」，你懂了它為什麼這樣運作，也知道怎麼親手把它組裝出來。剩下的，就是動手做你自己的東西了。

💡 想更進一步？這門課刻意當「入門」，還有很多值得深入的：微調 vs RAG vs Prompt 的決策、語音 Agent、本地/自架模型與隱私、Coding Agent 專題。挑一個你最有感的，繼續往下鑽吧。

← 回到課程首頁