Vincent5588 Wiki

Agent 建置與使用

閱讀時間約 10 分鐘

12. Agent 建置與使用

Agent 是讓 Claude 自主迭代 完成任務的代理人。 您之前用我「派 4 個 sub-agent 平行研究 Code/Skill/MCP/Agent」就是在用 Agent。

12.1 Agent 是什麼

跟一般對話 Claude 的差異

特性對話 ClaudeAgent
執行方式一次性回答迴圈執行（think → act → observe → repeat）
工具呼叫被動接受您的請求主動決策何時呼叫
續行能力無可自主迭代多輪
記憶共用 system prompt獨立上下文窗口
適用快速問答、摘要複雜多步驟任務

Agent Loop

flowchart LR
    A[Think 思考] --> B[Act 行動<br/>呼叫工具]
    B --> C[Observe 觀察<br/>看結果]
    C --> D{完成？}
    D -->|否| A
    D -->|是| E[回傳]

12.2 Anthropic Agent SDK

什麼是 Agent SDK：Anthropic 官方框架，讓您用 Python / TypeScript 編程定義 AI 代理。

誰適合用：

  • 後端工程師：自動化 API
  • DevOps：寫部署 / 監控 agent
  • 數據工程師：複雜 ETL 工作流
  • 非工程師：直接在 Cowork 用 sub-agent，不用寫程式

能做什麼：

  • 自動巡查 codebase 找 bug
  • 並行執行多任務（5 支 controller 同時改）
  • 多輪自主迭代完成需求
  • 與外部系統整合（DB、API、檔案）

vs Claude API

Claude APIAgent SDK
訊息層手動 request-response自動迴圈管理
Tools您解析SDK 自動
對話狀態您管理SDK 追蹤
受眾API 開發者Agent 開發者

12.3 Sub-agents（子代理）

Sub-agent 是主 Agent 派出的「小幫手」——獨立 context 跑，回報結果給主 Agent。主 agent 不被它的中間日誌淹沒。

主 Agent vs Sub-agent

項目主 AgentSub-agent
Context全專案脈絡隔離窗口
執行逐一派任務可並行 5+ 個
回報詳細過程摘要結果
適用協調流程特定深度任務

何時派

✅ 深度專注一個檔案 / 服務 ✅ 任務會產生大量日誌（grep / search） ✅ 想並行 3+ 個無關任務

❌ 跨檔案協調邏輯 ❌ 需要細緻人工審查的結果

12.4 Cowork 內建 5 種 Sub-agent

① claude-code-guide（Claude 知識顧問）

觸發：「Claude Code 快捷鍵？」「skill 怎麼寫？」
用途：查官方文件、回答 Claude 工具類問題
回報：文件摘要 + 連結

您剛才寫的這 4 章進階篇就是它幫研究的。

② Explore（codebase 探索者）

觸發：「掃 src/ 找所有 SQL 字串」
用途：parallel grep、目錄遍歷
回報：檔案清單 + 行號

③ general-purpose（通用代理）

觸發：「分析 logs/ 最後 100 行，找錯誤」
用途：自由形式分析、轉換、生成
回報：清晰結論 + 證據

④ Plan（架構師）

觸發：「這 5 支 controller 怎麼重構？」
用途：系統設計、API 規劃、技術決策
回報：結構圖 + 優缺點對比

⑤ statusline-setup（特殊設定）

觸發：系統內部自動使用
用途：設定 IDE 工具列

12.5 寫好 Sub-agent Prompt

與一般 Prompt 的關鍵差異

一般 prompt 可以假設 Claude 知道脈絡（您剛說什麼、檔案在哪）。 Sub-agent prompt 必須完全自包含——它沒看過您前面的對話。

❌ 不好

根據上面的程式碼，幫我 review

→ Sub-agent 不知道「上面」是什麼。

✅ 好

請開啟絕對路徑：
/Users/vincent/Projects/ExamSystem/Controllers/HrController.cs

掃描所有 SQL query，檢查 SQL injection 風險：
- 是否使用 parameterized query？
- 有沒有直接拼接使用者輸入？

回報格式 JSON：
{ filename, lineNo, risk, fix }

5 個最佳實踐

  1. 絕對路徑：不說「那個檔案」
  2. 背景一句話：「這是 PAM 系統的 HrController」
  3. 預期輸出格式：「JSON {field1, field2}」
  4. 限制範圍：「只看 src/，不看 tests/」
  5. Success criteria：「完成當你列出全部風險」

12.6 平行派 Agent

何時用平行

✅ 適合：

  • 5 支 controller 各自 review，無依賴
  • 同時掃 dev / staging / prod 日誌
  • 並行查 3 個資料表 schema

❌ 不適合：

  • A 結果是 B 輸入
  • 需全局一致性
  • 結果需逐一人工審

Cowork 範例

請派 3 個 sub-agent 平行做：
1. Explore：掃 backend/Controllers/ 找所有 SQL query
2. Explore：掃 backend/Services/ 找 async-await 混用
3. general-purpose：分析 docs/API_REFERENCE.md 找廢棄 API

我剛才幫您寫第 9-12 章時就是這樣派出去的——4 個 claude-code-guide 同時跑。

12.7 手把手用 Agent SDK 建一個 Agent（Python）

範例：自動產週報

from claude_agent_sdk import ClaudeSDKClient, tool
import asyncio
import subprocess
 
# 1️⃣ 定義工具
@tool("read_commit_log")
async def read_commits(args):
    """讀 git log，回傳最後 N 筆 commit"""
    result = subprocess.run(
        ["git", "log", f"-n {args['count']}", "--oneline"],
        capture_output=True, text=True
    )
    return {"commits": result.stdout}
 
@tool("get_pr_status")
async def get_prs(args):
    """查 GitHub PR 狀態（示意）"""
    return {
        "open_prs": 3,
        "merged_this_week": 5,
        "ready_for_review": ["#123", "#124"]
    }
 
# 2️⃣ 建立 Client
client = ClaudeSDKClient()
 
# 3️⃣ Agent 執行迴圈
async def generate_standup():
    prompt = """
    請自動生成週報，步驟：
    1. read_commit_log 查最近 10 筆 commit
    2. get_pr_status 看 PR 狀態
    3. 整理成：昨日完成 / 今日計畫 / 阻礙
    """
 
    response = await client.query(
        prompt=prompt,
        tools=[read_commits, get_prs],
        max_turns=5  # 最多 5 輪
    )
    print(response)
 
asyncio.run(generate_standup())

解析

元件作用
@tool註冊 Agent 可呼叫的工具
ClaudeSDKClientAgent 控制器
max_turns=5迭代上限（防無限迴圈）
await client.query自動 think → act → observe

12.8 Skills + Sub-agents 結合

能否在 Sub-agent 用 Skill？

✅ 能。但要在 prompt 明確呼叫：

派 sub-agent 用 /engineering:code-review skill 檢查這個 PR：
https://github.com/year-group/ExamSystem/pull/456

Sub-agent 自動：

  1. 把 /engineering:code-review 當工具呼叫
  2. 執行 skill 邏輯
  3. 回傳給主 agent

限制

  • Sub-agent 無法自動讀主 agent 的 CLAUDE.md
  • 若 skill 需要全局脈絡，要主動 paste

12.9 Memory 與 Context

Sub-agent 沒有主 context 怎麼辦

Sub-agent 上下文是隔離的，無法自動讀 CLAUDE.md。

解法：手動傳脈絡

這是系統脈絡：
- PAM = 績效考核系統，.NET + React
- 核心公式在 GradingService.cs（單一來源原則）
- 禁止重複實作

任務：掃 backend/Services/ 找有沒有人直接算分數而不呼叫 GradingService

最佳實踐

  • 用註解 / 文件傳脈絡，不依賴隱含知識
  • Sub-agent 回報附「已驗證符合 CLAUDE.md §4」
  • 主 agent 複檢結果

12.10 Agent 失控 → 3 層防護

# 1️⃣ 迴圈上限
response = await client.query(prompt="...", max_turns=5)
 
# 2️⃣ 限制工具集（不給危險工具）
response = await client.query(
    prompt="...",
    tools=[safe_tool_1, safe_tool_2]  # 不給 rm 工具
)
 
# 3️⃣ Stop Condition（明確結束條件）
prompt = "完成當你列出全部 SQL injection 風險"

手動停止

Cowork 右上角 ⏹️ Stop 鈕立即中止。

防誤解

❌ 模糊：「優化這個服務」

✅ 清晰：

只檢查 HrController.cs 內 3 個方法的 N+1 問題：
- GetGradeDistribution
- SubmitDepartment
- RecalculateGradeDistribution
找出 → 寫測試驗證 → 停止

12.11 PAM 場景的 Agent 應用

場景 1：自動產週報

派 general-purpose sub-agent：
「掃 git log 最近 7 天 PAM repo，列出：
- 合併的 PR + reviewers
- 開啟中 PR + 誰在 review
- 關閉的 issue
整理成 standup 格式」

場景 2：codebase 巡查

派平行 3 sub-agent：
1. Explore：掃 backend/ 找直接拼 SQL 的地方
2. Explore：掃 frontend/ 檢查缺 /api/hr/ 授權的呼叫
3. Plan：分析 ServiceLayer 評估漏掉的驗證層

場景 3：同時改 5 支 Controller

派平行 5 個 general-purpose：
1. ReviewController.cs → decimal(5,2) → (6,3)
2. HrController.cs → 同步改
3. NotificationController.cs → 同步改
4. xUnit 測試 → 更新 mock 期望值
5. EF Core migration → 寫 migration
各自獨立完成 + 回報

上面這個如果手動做要 1 小時；派出去 5 個平行 sub-agent，10 分鐘搞定。

12.12 排錯 FAQ

Q解
Agent 一直迴圈max_turns=3、prompt 加「完成當你…」stop condition
Sub-agent 找不到檔案改絕對路徑，不要相對路徑
Sub-agent 沒用 skill確認 skill 名稱（/list-skills 查）
Sub-agent 回報不清楚prompt 加「回報為 JSON」或「條列式」
並行 agent 互卡同時改同檔 → 改成序列或分檔

12.13 官方資源

🎓 結語

恭喜！您讀完 12 章 Claude 學習指南。從「不熟」到「能建置 Code / Skill / MCP / Agent」，完整 stack 都有了。

下一步建議：

  1. 跑一遍 09-Claude Code 建置與使用 第 9.5 節的 /init，給您 PAM 專案
  2. 建第一個 skill（10-Skill 建置與使用 第 10.7 節範例）
  3. 連一個 MCP（11-MCP 建置與使用 11.4 從 Cowork 連 Notion 開始）
  4. 派一個 sub-agent（在 Cowork 試「派 explorer 看 PAM 全 codebase」）

任何時候卡住，回來查、或在 Cowork 直接問我「我想做 X 但不會」。

← 上一章 11-MCP 建置與使用 回到 Claude 學習指南目錄

關係圖譜

反向連結