模組 2：多 Agent 3 / 6
中階 Session 9 Agent Teams Communication

Agent Teams 與通訊

探索 TeammateManager 和 JSONL 訊息匯流排如何實現多代理協作。

2026年3月20日 20 分鐘閱讀

你將學到什麼

子代理（第 4 堂課）解決了個別子任務的上下文隔離問題。但持續的、進行中的協作呢？如果你需要一個代理寫程式碼而另一個代理審查它，兩者都在多個輪次中維護自己的上下文呢？

這就是 Agent Teams 發揮作用的地方 — 多個 Claude Code 實例並列運行，每個都有自己的上下文視窗，通過共享的訊息匯流排進行通訊。

完成後，你將了解：

  • Agent Teams 與子代理有何不同
  • TeammateManager 協調層
  • JSONL 訊息匯流排如何實現代理間通訊
  • 團隊拓撲：名稱、角色和訊息傳遞模式
  • 常見多代理工作流程的實用設定

問題是什麼

子代理強大但短暫。它們生成、執行任務、返回結果、然後消失。它們的上下文被丟棄。這對一次性的研究或探索來說很完美，但對持續協作就不適用了：

Subagent Limitation:

  Turn 1: Spawn reviewer agent → reviews code → result → context gone
  Turn 2: Spawn reviewer agent → has no memory of Turn 1 review
  Turn 3: Spawn reviewer agent → starts from scratch again

  Each review is isolated. The reviewer can't track
  whether its previous feedback was addressed.

在規模化時你還會遇到上下文污染問題。如果你正在建構一個複雜功能，實作者的上下文被程式碼填滿，審查回饋堆疊在上面。最終，單一上下文視窗無法同時容納實作細節和審查歷史。

你需要的是擁有獨立上下文的持久代理，它們可以彼此交談：

Agent Teams:

  ┌─────────────────┐     ┌─────────────────┐
  │  Implementer    │     │  Reviewer        │
  │  (own context)  │◄───►│  (own context)   │
  │                 │     │                  │
  │  Remembers all  │     │  Remembers all   │
  │  code written   │     │  review feedback │
  └─────────────────┘     └─────────────────┘
         │                        │
         └──────────┬─────────────┘
                    │
            ┌───────▼────────┐
            │  JSONL Message │
            │  Bus (shared)  │
            └────────────────┘

如何運作

啟用 Agent Teams

Agent Teams 是一個通過環境變數啟用的實驗性功能：

export CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS=1

啟用後，你可以在 Claude Code 會話中使用鍵盤快捷鍵建立隊友：

快捷鍵動作
Shift+Up / Shift+Down選擇隊友
Shift+Tab進入委派模式（發送任務給隊友）
Ctrl+T查看所有隊友的任務清單

每個隊友作為獨立的 Claude Code 程序運行，擁有自己的終端、自己的上下文視窗和自己的對話歷史。

TeammateManager

TeammateManager 是追蹤會話中所有活躍隊友的協調層。它維護一個註冊表，記錄誰是活躍的、他們的角色以及通訊頻道：

┌──────────────────────────────────────────────────┐
│                TeammateManager                    │
│                                                   │
│  Registry:                                        │
│  ┌─────────────────────────────────────────┐     │
│  │  Name: "implementer"                    │     │
│  │  Role: "Write and modify source code"   │     │
│  │  Status: active                         │     │
│  │  Context: [independent message array]   │     │
│  ├─────────────────────────────────────────┤     │
│  │  Name: "reviewer"                       │     │
│  │  Role: "Review code and suggest fixes"  │     │
│  │  Status: active                         │     │
│  │  Context: [independent message array]   │     │
│  ├─────────────────────────────────────────┤     │
│  │  Name: "tester"                         │     │
│  │  Role: "Write and run tests"            │     │
│  │  Status: active                         │     │
│  │  Context: [independent message array]   │     │
│  └─────────────────────────────────────────┘     │
│                                                   │
│  Message Bus: ~/.claude/teams/session-xyz.jsonl   │
│                                                   │
└──────────────────────────────────────────────────┘

註冊表中的每個隊友都有：

  • 名稱 — 用於定址訊息的唯一識別碼
  • 角色 — 塑造隊友行為的描述
  • 狀態 — 隊友是否活躍、閒置或已完成
  • 上下文 — 獨立的訊息陣列（隊友自己的對話）

JSONL 訊息匯流排

隊友通過基於檔案的 JSONL 訊息匯流排進行通訊。每條訊息是一行 JSON，附加到共享檔案中：

Communication Flow:

  Implementer                    Reviewer
  ┌──────────┐                  ┌──────────┐
  │ writes   │    message.jsonl │ reads     │
  │ code     │───────────────►  │ message   │
  │          │                  │ reviews   │
  │ reads    │  ◄───────────────│ sends     │
  │ feedback │    message.jsonl │ feedback  │
  └──────────┘                  └──────────┘

匯流排上的訊息看起來像這樣：

{"from": "implementer", "to": "reviewer", "type": "request", "content": "I've finished the auth middleware in src/middleware/auth.ts. Please review for security issues.", "timestamp": "2026-03-20T10:15:30Z"}
{"from": "reviewer", "to": "implementer", "type": "response", "content": "Found 2 issues: (1) JWT secret is hardcoded on line 15, use env var. (2) No rate limiting on login endpoint.", "timestamp": "2026-03-20T10:16:45Z"}
{"from": "implementer", "to": "reviewer", "type": "request", "content": "Fixed both issues. JWT secret now from process.env.JWT_SECRET, added rate-limiter-flexible on /login. Ready for re-review.", "timestamp": "2026-03-20T10:18:20Z"}

為什麼用 JSONL？它相比基於網路的通訊有幾個優勢：

  • 僅追加 — 多個代理同時寫入不會衝突
  • 持久性 — 代理重啟後訊息仍存在
  • 可檢視 — 你可以讀取檔案查看完整的通訊歷史
  • 簡單 — 不需要伺服器、連接埠、網路 — 只是一個檔案

SendMessage 工具

隊友使用 SendMessage 工具進行通訊：

{
  "type": "tool_use",
  "name": "SendMessage",
  "input": {
    "to": "reviewer",
    "content": "The auth middleware is ready for review. Key files: src/middleware/auth.ts, src/routes/auth.ts"
  }
}

接收的隊友會在下一輪中看到訊息作為系統通知，類似於背景任務完成的回報方式（第 8 堂課）。

規模化的上下文隔離

Agent Teams 相比單一代理的根本優勢在於上下文隔離。比較：

Single Agent (200K context):
  ┌──────────────────────────────────────────────┐
  │  System prompt          ~3K tokens           │
  │  Implementation code    ~50K tokens          │
  │  Review feedback        ~20K tokens          │
  │  Test output            ~15K tokens          │
  │  Documentation          ~10K tokens          │
  │  ─────────────────────────────────────       │
  │  Total: ~98K tokens     (49% capacity)       │
  │  All competing for the same context window   │
  └──────────────────────────────────────────────┘

Agent Team (200K x 3 contexts):
  ┌─────────────────┐  ┌─────────────────┐  ┌─────────────────┐
  │  Implementer    │  │  Reviewer        │  │  Tester          │
  │  ~53K tokens    │  │  ~23K tokens     │  │  ~18K tokens     │
  │  (27% capacity) │  │  (12% capacity)  │  │  (9% capacity)   │
  │                 │  │                  │  │                  │
  │  Deep code      │  │  Deep review     │  │  Deep test       │
  │  context        │  │  context         │  │  context         │
  └─────────────────┘  └─────────────────┘  └─────────────────┘
  Total: 600K tokens available, each domain has room to breathe

每個隊友可以在自己的領域深入，而不會排擠到其他人。審查者可以保存豐富的審查歷史，而不會減少實作者可用的程式碼上下文空間。

關鍵洞見

Teams 給予每個代理自己的上下文視窗，在比子代理更大的規模上解決上下文污染問題。 子代理是無狀態的 — 它們生成、執行然後消失。隊友是有狀態的 — 它們在多個輪次中持續存在、累積領域知識、參與持續對話。

這與真實工程團隊的工作方式如出一轍。程式碼審查者不會在你要求他們查看下一個 Pull Request 時忘記之前的審查。QA 工程師在測試本週的建構時會記得他們上週發現的 bug。持久的上下文使累積的專業知識成為可能。

JSONL 訊息匯流排是讓這一切運作的黏合劑。沒有它，隊友會成為孤立的孤島。有了它，它們形成一個協作團隊，每個成員貢獻自己的專業視角，同時維護自己連貫的上下文。

使用基於檔案的訊息傳遞（JSONL）而非網路協定的設計選擇是有意的。檔案簡單、可除錯，且不需要基礎設施。你可以 cat 訊息匯流排來查看代理之間到底在說什麼。這種透明度對建立信任至關重要 — 你始終知道代理之間發生了什麼。

實作範例

建立實作者 + 審查者團隊

以下是如何為功能開發工作流程建立一個雙代理團隊：

Terminal 1 — Implementer:
  $ export CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS=1
  $ claude
  > I'm the implementer. I'll write the code for the
    notification system.

Terminal 2 — Reviewer:
  $ export CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS=1
  $ claude
  > I'm the reviewer. I'll review code that the implementer
    produces and provide security and quality feedback.

兩者都運行後，工作流程看起來像這樣：

Implementer                         Reviewer
────────────                        ────────────
Writes notification model
  └── src/models/notification.ts

Sends: "Model ready for review"
                          ────────►
                                    Reviews model
                                    Sends: "Add index on
                                    userId for query perf"
                          ◄────────

Adds index, continues to
write API endpoints
  └── src/routes/notifications.ts

Sends: "Endpoints ready"
                          ────────►
                                    Reviews endpoints
                                    Sends: "LGTM, but add
                                    pagination to GET /list"
                          ◄────────

Adds pagination, marks
feature complete

三代理團隊：實作、審查、測試

對於較大的功能，加入一個測試代理：

Team Configuration:

  Implementer                Reviewer                 Tester
  ┌─────────────┐           ┌─────────────┐          ┌─────────────┐
  │ Writes code │──message──│ Reviews code │          │ Writes tests│
  │             │           │ for quality  │          │ Runs tests  │
  │             │◄─feedback─│ and security │          │             │
  │             │           └─────────────┘          │             │
  │             │──────────message────────────────── │             │
  │             │◄─────────test results──────────────│             │
  └─────────────┘                                    └─────────────┘

  Workflow:
  1. Implementer writes feature code
  2. Reviewer reviews it (in parallel with step 3)
  3. Tester writes test cases based on the feature spec
  4. Implementer addresses review feedback
  5. Tester runs tests against the updated code
  6. All agents converge: code + reviews + green tests

通訊模式

三種模式主導代理團隊通訊：

1. 請求-回應（最常見）：

Implementer → Reviewer: "Please review src/auth.ts"
Reviewer → Implementer: "Found 2 issues: ..."

2. 廣播（向所有人宣布）：

Implementer → All: "Breaking change: renamed User to Account
in all models. Update your references."

3. 委派（指派任務）：

Implementer → Tester: "Write unit tests for the new
  notification model. Cover: create, read, mark-as-read,
  delete. Expected file: src/models/notification.test.ts"

何時使用 Teams vs. 子代理

標準子代理Agent Teams
任務持續時間短暫、一次性持續、多輪
上下文需求使用後丟棄跨輪次持久保留
通訊方式結果返回一次持續對話
設定成本零（自動）需要明確設定
典型用途探索、研究實作、審查
代理數量1-3 個短暫代理2-4 個持久代理
上下文視窗父代理 + 臨時子代理所有獨立、所有持久

經驗法則：如果任務是「找到 X 然後回報」，使用子代理。如果任務是「跟我一起處理 X 接下來的 30 分鐘」，使用隊友。

除錯團隊通訊

由於訊息匯流排是純文字 JSONL 檔案，你可以檢視它：

# See all messages between agents
cat ~/.claude/teams/session-xyz.jsonl | python3 -m json.tool

# Filter messages from a specific agent
grep '"from": "reviewer"' ~/.claude/teams/session-xyz.jsonl

# Count messages per agent
grep -o '"from": "[^"]*"' ~/.claude/teams/session-xyz.jsonl | sort | uniq -c

這種透明度意味著你可以隨時審計代理之間的討論內容、及早發現溝通不良，並了解團隊是如何協調的。

前後對比

單一代理Agent Teams
所有事物共用一個上下文視窗每個隊友有獨立上下文
上下文被混合關注點填滿每個代理專注於自己的領域
沒有持久協作隊友維持持續對話
審查需要同時載入審查和程式碼上下文審查者有專用的審查歷史上下文
循序：寫、然後審查、然後測試平行：審查者和測試者在實作者寫程式時同步工作
對程式碼的單一觀點多個專業化的觀點

下一堂課

這結束了核心的多代理概念。第 10 堂課探討團隊協定 — 使代理團隊在規模化時可預測且有效的結構化通訊模式和慣例。