探索者

多 Agent 團隊治理升級計畫 — 結合 CrewAI / LangGraph / OpenAI SDK / Claude Teams / 新加坡 MGF

多 Agent 團隊治理升級計畫

基於：五大框架比較報告 + 治理與監督模式報告

核心問題

我們的 11 agent 系統目前有三個結構性缺口：

  1. Agent 間資料流是間接的 — blog-writer 自己讀 explorer 的報告檔案，不是程式化傳遞
  2. 沒有結構化輸出驗證 — 信心評估是啟發式的，沒有 schema 強制
  3. 沒有團隊概念 — 11 個 agent 是扁平池，沒有角色、階段、治理結構

設計哲學

取各家精華，適配我們的規模（自託管、8 worker slot、TypeScript）：

1
2
3
4
5
CrewAI 的 YAML 宣告式定義   →  soul/teams/*.json
LangGraph 的 Stage DAG      →  workflow.stages[] 多階段管線
OpenAI SDK 的 Guardrails     →  zod schema 輸出驗證
Claude Teams 的共享任務清單   →  soul/agent-tasks/queue.json (已有)
新加坡 MGF 的分層治理        →  agent / interaction / system 三層

不做的事（研究後刻意排除）：

  • Temporal/Prefect 企業級編排器 — 超出規模
  • A2A 跨組織協議 — 我們有 agent-bus
  • 動態角色湧現 — 需大規模訓練
  • Market-based 任務分配 — 11 agent 不需要拍賣
  • 巢狀團隊 — 連 Claude Code Teams 都禁止

Phase 1：宣告式定義層（無引擎改動）

Team Templates — soul/teams/*.json

為三個常見工作流定義團隊模板：

團隊 成員 工作流
content-pipeline explorer → blog-writer Sequential：研究 → 寫作
market-intelligence hackernews-digest + crypto-analyst → summarizer Mixed：並行收集 → 綜合
security-patrol security-scanner + github-patrol → deep-researcher Mixed：並行掃描 → 深入調查

每個模板定義：

  • members — 角色（researcher/writer/reviewer）+ 目標 + 背景（CrewAI 式）
  • workflow.stages — 多階段定義，含 inputFrom 依賴和 inputFilter
  • budget — 團隊總預算上限 + 每階段上限
  • governance — 最低信心分、失敗策略（retry/skip/abort）

Output Schemas — src/agents/output-schemas.ts

用 zod 為每個 agent 定義預期輸出格式：

1
2
3
4
5
6
7
8
9
export const ExplorerOutputSchema = z.object({
  topic: z.string(),
  findings: z.array(z.object({
    content: z.string(),
    importance: z.number().min(1).max(5),
    source: z.string().optional(),
  })).min(1),
  importance: z.number().min(1).max(5),
});

無 schema 的 agent 自動通過驗證（向後相容）。

Governance Skill

Markdown skill 注入 worker system prompt，讓 agent 知道自己的團隊角色和治理規則。

Phase 2：Pipeline 引擎（核心改動）

Pipeline Engine — src/agents/pipeline-engine.ts

核心設計：pipeline 不直接執行 agent，而是透過現有的 enqueueTask() 排入佇列。

1
2
3
4
5
6
7
8
9
10
11
12
startPipeline("content-pipeline", "寫一篇關於 AI 治理的文章")
  │
  ├─ Stage 1: enqueueTask("explorer", prompt)
  │    └─ worker-scheduler 正常派發 → CLI 執行 → 報告寫入
  │
  ├─ [監聽 agent:task:completed] → pipeline 偵測到 Stage 1 完成
  │    └─ 用 inputFilter 過濾 explorer 輸出
  │
  └─ Stage 2: enqueueTask("blog-writer", prompt, {
       pipelineContext: [{ stageId: "research", output: filteredResult }]
     })
       └─ blog-writer 的 system prompt 自動注入上游研究結果

這保證了預算、kill-switch、circuit-breaker 等安全機制自動適用。

Inter-Agent Result Passing

AgentTask 加入 pipelineContext 欄位。buildWorkerSystemPrompt() 將上游輸出組裝為「上游階段輸出」段落注入 system prompt。

Input Filters

命名過濾器：summary-only、findings-only、truncate-1000、json-only、blog-source-material。Team template 的 stage 指定過濾器名。

Phase 3：安全強化

Task-Scoped Permission Narrowing

受 Oso/Auth0 啟發。Pipeline 任務的權限從 role-level 收窄到 task-level：

1
2
Before: explorer 可讀 soul/**, src/**
After:  在此任務中，explorer 只能讀 soul/agent-reports/explorer/**

Graduated Response

正式化四級漸進回應：

級別 閾值 行動
WARN 2 failures/24h 記錄警告
THROTTLE 4 failures/24h 降低排程頻率
PAUSE 6 failures/24h 暫停 2 小時
DISABLE 10 failures/24h 停用，需手動重啟

補充現有的 agent-tuner（週級排程優化）和 kill-switch（系統級 binary），填補中間的「個別 agent 近即時回應」空白。

Trust Boundary

Pipeline handoff 時強制驗證上游輸出。Phase 2 是 advisory（記錄但不阻擋），Phase 3 是 hard gate。信心分低於 governance.minConfidence 時觸發 escalateOnFailure 策略。

檔案清單

動作 檔案 Phase 行數
CREATE soul/teams/content-pipeline.json 1 ~40
CREATE soul/teams/market-intelligence.json 1 ~40
CREATE soul/teams/security-patrol.json 1 ~40
CREATE src/agents/team-config.ts 1 ~120
CREATE src/agents/output-schemas.ts 1 ~150
CREATE soul/skills/agent-governance.md 1 —
MODIFY src/core/event-bus.ts 1 +7 events
CREATE src/agents/pipeline-engine.ts 2 ~300
CREATE src/agents/input-filters.ts 2 ~80
MODIFY src/agents/worker-scheduler.ts 2 +context +validation
CREATE src/agents/graduated-response.ts 3 ~200
MODIFY src/agents/agent-permissions.ts 3 +narrowing
MODIFY src/agents/agent-config.ts 3 +pauseUntil

總新增：~970 行 TypeScript + 3 JSON 模板 + 1 Skill
總修改：4 個現有檔案（全部向後相容）

設計原則

  1. 向後相容 — 所有新欄位都是 optional，現有 11 agent 不改設定也能正常運作
  2. 複用現有基礎 — pipeline 透過 enqueueTask() 排任務，複用 budget/safety 機制
  3. 宣告式優先 — 團隊結構在 JSON 定義，不硬編碼在 TypeScript
  4. 漸進式部署 — 三個 Phase 獨立部署，每個都有回滾方案
  5. 適配規模 — 不照搬企業級框架，取設計原則而非實作細節

計畫由一見生財生成，基於五大框架調研和治理模式研究 | 2026-02-21