研究日期

2026-04-06

簡介

2026 年的 AI 工程圈有一個共識正在快速成形：模型能力只是上限，真正決定 agent 是否可用、可控、可部署的是 harness。

什麼是 Harness？簡單說，它不是 Agent 本身（推理、決策、規劃），也不是 Tool（被呼叫的能力單元），而是把 LLM/Agent「變成可用系統」的執行外殼與控制平面。如果 Agent 是「大腦」，Tool 是「手腳」，那 Harness 就是「神經系統＋操作系統＋安全邊界」。

這個概念源自傳統軟體工程中的 test harness——建立可控環境去驗證被測系統。如今它已演進為涵蓋工具接入、狀態管理、sandbox、workflow orchestration、feedback loop、policy guardrails、evaluation 與 observability 的完整工程學科。

OpenAI 在 2026 年初發布了 Harness Engineering 一文，描述其團隊以 Codex 產出近百萬行程式碼、約 1,500 PRs，且人類幾乎不手寫 code。Martin Fowler 也在 2026 年 4 月發表 Harness Engineering for Coding Agent Users，正式把這門學問工程化。LangChain 則在 The Anatomy of an Agent Harness 中提出了一個公式：Agent = Model + Harness。

本文將從原理到實作，系統性地拆解 Harness Engineering。

核心概念

Harness vs Agent vs Tool

  flowchart TB
    subgraph Harness["🔧 Harness（控制平面）"]
        SM[Session Manager]
        MR[Message Router]
        TE[Tool Executor]
        PE[Permission Layer]
        CL[Context & Memory]
        ORC[Orchestrator]
    end

    subgraph Agent["🧠 Agent（推理平面）"]
        LLM[LLM Core]
        PLAN[Planning]
        DEC[Decision Making]
    end

    subgraph Tools["🛠️ Tools（能力平面）"]
        T1[Shell]
        T2[File I/O]
        T3[Web/API]
        T4[Browser]
        T5[MCP Servers]
    end

    Harness --> Agent
    Agent --> Harness
    Harness --> Tools
    Tools --> Harness

Feedforward + Feedback 框架

Martin Fowler 提出了一個控制論框架來理解 harness：

• Guides（Feedforward）：在 agent 執行前就注入正確的上下文與約束，提高首次做對的機率

  • System prompts、CLAUDE.md/AGENTS.md、rules、skills
  • Task decomposition、plan templates
  • Policy pre-configuration

• Sensors（Feedback）：在 agent 執行後收集結果並建立修正迴路

  • Computational：tests、linters、type checkers、CI
  • Inferential：LLM judge、semantic review、code review agent

失敗時不是叫模型「try harder」，而是補齊 missing capability 或建立 legible/enforceable scaffold。

架構與原理

核心模組架構

一個生產級的 AI Agent Harness 通常包含以下七個核心模組：

  flowchart TD
    UI[User / IDE / CLI / Channel] --> H[Harness Frontend]
    H --> SM[Session Manager]
    SM --> MR[Message Router / Event Bus]
    MR --> ARA[Agent Runtime Adapter]
    ARA --> LLM[LLM / Agent Core]
    MR --> TE[Tool Executor]
    TE --> MC[MCP Client Layer]
    MC --> MS1[MCP Server: Git]
    MC --> MS2[MCP Server: Browser]
    MC --> MS3[MCP Server: DB/API]
    H --> PE[Permission / Policy Engine]
    PE --> TE
    SM --> CL[Context & Memory Layer]
    SM --> ORC[Orchestrator]
    ORC --> ARA

1. Session Manager

職責：管理 agent 的整個生命週期。

• 建立 session_id / run_id
• 維護狀態機：created → running → awaiting → completed | failed | cancelled
• 保存對話歷史、工具執行歷史、artifact 索引
• 支援 resume / retry / cancel
• 支援 context compaction / summarization

狀態轉換：

  stateDiagram-v2
    [*] --> created
    created --> running: submit prompt
    running --> awaiting: need human input
    running --> completed: task done
    running --> failed: error
    running --> cancelled: cancel
    awaiting --> running: human resume
    awaiting --> cancelled: cancel
    completed --> [*]
    failed --> running: retry
    cancelled --> [*]

常見實作模式：

• In-memory + WAL/log append：本地 CLI 最快
• DB-backed：Postgres / SQLite / Redis，適合 distributed / HA
• Event-sourced：所有訊息/工具事件先 append，再 materialize view

關鍵原則：Session state 跟 message history 要分離。用 event log + projection 而非單一 blob 更新，才能支援 partial replay。

偽代碼：

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27

type SessionState = "created" | "running" | "awaiting" | "completed" | "failed" | "cancelled";

class SessionManager {
  async createSession(input: CreateInput): Promise<Session> {
    const session = {
      sessionId: uuid(),
      runId: uuid(),
      state: "created",
      history: [],
      toolCalls: [],
      artifacts: [],
      createdAt: Date.now()
    };
    await store.save(session);
    return session;
  }

  async appendEvent(sessionId: string, event: Event) {
    await eventLog.append(sessionId, event);
    return materializer.apply(sessionId, event);
  }

  async resume(sessionId: string, humanInput: string) {
    await this.appendEvent(sessionId, { type: "human.resume", input: humanInput });
    await this.transition(sessionId, "running");
  }
}

2. Message Router

職責：處理所有來源的事件流，決定路由去向。

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29

type Event =
  | { type: "user.message"; content: Message[] }
  | { type: "model.delta"; delta: string }
  | { type: "model.tool_call"; name: string; args: any; callId: string }
  | { type: "tool.stdout"; callId: string; chunk: string }
  | { type: "tool.result"; callId: string; result: any }
  | { type: "agent.await"; schema: any; prompt: string }
  | { type: "subagent.result"; agent: string; output: Message[] };

async function routeEvent(session: Session, event: Event) {
  switch (event.type) {
    case "user.message":
      context.add(event.content);
      break;
    case "model.delta":
      stream.emitToUI(event.delta);  // 即時串流給使用者
      break;
    case "model.tool_call":
      queue.enqueueTool(event);       // 排隊執行工具
      break;
    case "tool.result":
      context.add(formatToolResult(event));  // 結果送回上下文
      break;
    case "agent.await":
      session.state = "awaiting";
      ui.requestHumanInput(event);    // 等待人類輸入
      break;
  }
}

最佳實踐：

• UI stream 與 durable event stream 分開
• Tool stdout/stderr 不要直接全灌回 prompt，先聚合或截斷
• Router 需支援 backpressure，否則 streaming tool output 會拖垮 UI

3. Tool Executor

職責：統一管理工具呼叫的生命週期。

• Schema validation（JSON Schema）
• Timeout / retry / concurrency limit
• Stdout/stderr capture 與串流
• Side-effect 標記（read / write / destructive / network）
• Result normalization

實作模式：

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19

class ToolExecutor:
    async def execute(self, tool_call, policy, sandbox):
        tool = registry.get(tool_call.name)
        validated = tool.schema.validate(tool_call.args)

        # 權限檢查（硬邏輯，不是靠 prompt）
        decision = policy.check(tool.metadata, validated)
        if decision == "deny":
            return ToolError("permission denied")
        if decision == "ask":
            await ask_user(tool_call)

        # 在 sandbox 內執行
        async with sandbox.session(tool.sandbox_profile) as env:
            result = await run_with_timeout(
                tool.invoke(validated, env=env),
                timeout=tool.timeout_s
            )
            return normalize_result(result)

4. Permission Layer / Policy Engine

核心原則：權限判斷不能只是 prompt 裡的一句話，必須是硬邏輯層。

Policy 維度：

  flowchart LR
    A[File Scope] --> D{Policy Decision}
    B[Side Effect Level] --> D
    C[Trust Level] --> D
    E[Tool Annotation] --> D
    F[Environment] --> D
    D -->|allow| G[執行]
    D -->|ask| H[人類審批]
    D -->|deny| I[拒絕]

1
2
3
4
5
6
7
8
9

function checkPolicy(action: Action, ctx: Context): Decision {
  if (action.path && isProtectedPath(action.path)) return "deny";
  if (action.network && !ctx.sandbox.networkEnabled) return "ask";
  if (action.destructive) return "ask";
  if (action.path && !isInsideWorkspace(action.path)) return "ask";
  // 從網頁抓取的內容視為 untrusted
  if (ctx.source === "untrusted_web" && action.tool === "Bash") return "deny";
  return "allow";
}

典型分層（從低到高風險）：

1. Read — 讀取檔案、搜尋、查詢
2. Edit — 修改現有檔案
3. Exec — 執行命令
4. Network — 網路請求
5. Credential — 存取金鑰、憑證
6. External Side Effects — git push、deploy、發布、發郵件

5. Context & Memory Layer

• 短期上下文（對話歷史 + system prompt）
• 長期記憶（跨 session 的知識持久化）
• 摘要 / 壓縮機制（避免 context window 超限）
• 支援多種 storage backend：vector DB、KV store、file-based

6. Transport / Protocol Adapters

Harness 需要支援多種通訊協議：

• MCP（Model Context Protocol）：tool/resource 接入
• ACP（Agent Communication Protocol）：agent session 控制
• CLI/TUI：終端機互動
• WebSocket / SSE：即時串流
• HTTP/REST：API endpoint

7. Orchestrator

管理單 agent loop 或多 agent 協作：

  flowchart TD
    ORC[Orchestrator] --> A[Worker A: Research]
    ORC --> B[Worker B: Coding]
    ORC --> C[Worker C: Review]
    ORC --> D[Synthesizer: Merge]
    A --> ORC
    B --> ORC
    C --> ORC
    D --> ORC

Orchestrator 要提供：sub-session identity、ownership、result propagation、cancellation tree、concurrency limits、message isolation。

ACP 與 MCP：Harness 的兩大協議

MCP（Model Context Protocol）— 能力平面

MCP 是目前最成熟的 agent 工具接入標準，基於 JSON-RPC 2.0。

核心概念：

• 三個角色：Host / Client / Server
• Server 提供：Resources、Tools、Prompts
• Client 可提供：Sampling
• 支援 capability negotiation、stateful connection

在 Harness 中的正確整合方式：

  flowchart LR
    U[User/UI] --> H[Harness Host]
    H --> PE[Permission Engine]
    H --> TE[Tool Executor]
    TE --> MC1[MCP Client A]
    TE --> MC2[MCP Client B]
    MC1 --> S1[MCP Server: Git/Jira]
    MC2 --> S2[MCP Server: Browser/DB]

關鍵原則：

• Harness 是 Host，不應該把 MCP server 直接暴露給模型
• 每個 MCP server connection 最好是獨立 client instance
• Host 決定哪些 resources/tools 可見、哪些要 ask、哪些給哪些 subagent 用
• MCP tool descriptions 可能是 untrusted，不要盲目信任
• 遠端 MCP server 不應看到完整對話

2026 Roadmap 重點：

• Transport scalability
• Agent communication（Tasks primitive, SEP-1686）
• Governance maturation
• Enterprise readiness

ACP（Agent Communication Protocol）— 控制平面

ACP 目前有多個同名但不同定位的協議：

BeeAI ACP 的核心概念（最完整的 ACP 實作）：

• Run lifecycle：created → in-progress → awaiting → cancelling → cancelled → completed → failed
• 三種 run mode：sync / async / stream
• Await 機制：agent 可請求 client 補資料再 resume
• Session continuity：跨 run 的狀態延續
• 多模態 message parts：text、image、citation、trajectory metadata

 1
 2
 3
 4
 5
 6
 7
 8
 9
10

@server.agent()
async def agent(input: list[Message], context: Context):
    yield {"thought": "analyzing request"}
    if missing_info(input):
        resume = yield {
            "await": {
                "prompt": "Please provide repository URL"
            }
        }
    yield Message(role="agent/my-agent", parts=[...])

實務建議：

• 本地 coding harness：MCP 用於 tool/plugin，ACP 用於 agent-to-client
• Session manager 保持本地 truth，ACP adapter 只是 transport façade
• 不要把核心 state 綁死在協定

MCP 解決能力接入；ACP 解決 agent session 控制。兩者互補，不互斥。

真實案例分析

OpenAI Codex CLI

OpenAI Codex 是「agent-first CLI harness」的代表。從其開源 repo（codex-rs/core/src）可觀察到清晰的模組分離：

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13

codex-rs/
├── core/src/
│   ├── agent/              # Agent runtime
│   ├── context_manager/    # 上下文管理
│   ├── exec.rs             # 執行引擎
│   ├── exec_policy.rs      # 權限策略（核心！）
│   ├── function_tool.rs    # 工具映射
│   ├── event_mapping.rs    # 事件轉換
│   ├── file_watcher.rs     # 檔案監控
│   └── config_loader/      # 設定載入
└── exec/src/
    ├── event_processor.rs  # 機器端輸出
    └── event_processor_with_human_output.rs  # 人類端輸出

設計亮點：

• Policy / event / tool / context 模組分得清楚
• Human-readable 與 JSONL output processor 分離，自動化與互動共存
• Sandbox 與 approval 不是附屬功能，是核心能力
• macOS 用 Seatbelt，Linux 用 bubblewrap + seccomp / Landlock

Claude Code

Claude Code 是「terminal-native + repo-native harness」的代表：

• 內建 Read / Write / Edit / Bash / Glob / Grep / WebSearch / WebFetch
• Hooks 系統：PreToolUse / PostToolUse / Stop / SessionStart / SessionEnd…
• Subagents 有獨立 context、權限、memory
• 記憶設計：instruction memory（CLAUDE.md）+ auto-notes（agent 自動學習）
• 支援多 surface：Terminal / IDE / Desktop / Web

設計亮點：

• Hooks 是最乾淨的 governance extension point
• Subagent 不是平行 thread，而是有 scope / tools / permission / memory 的 specialized runtime

Cursor / Windsurf

Cursor — IDE-native harness：

• Editor state / selection / repo context 作為自然上下文
• Tool surface 偏編輯器能力、終端、檔案、搜尋
• 特別重視「編輯-預覽-接受」的 UX flow

Windsurf（Cascade） — IDE + agent workflow：

• 除了基本工具，加入了 Memories、Rules、AGENTS.md、Workflows、Skills
• 把 harness 做成 agent operating environment

開源框架

實作範例：最小可用 Harness

以下展示一個最小化的 Harness 核心架構，用於理解各組件如何協作：

  1
  2
  3
  4
  5
  6
  7
  8
  9
 10
 11
 12
 13
 14
 15
 16
 17
 18
 19
 20
 21
 22
 23
 24
 25
 26
 27
 28
 29
 30
 31
 32
 33
 34
 35
 36
 37
 38
 39
 40
 41
 42
 43
 44
 45
 46
 47
 48
 49
 50
 51
 52
 53
 54
 55
 56
 57
 58
 59
 60
 61
 62
 63
 64
 65
 66
 67
 68
 69
 70
 71
 72
 73
 74
 75
 76
 77
 78
 79
 80
 81
 82
 83
 84
 85
 86
 87
 88
 89
 90
 91
 92
 93
 94
 95
 96
 97
 98
 99
100
101
102
103
104
105
106
107
108
109
110
111
112
113

// ========== 最小 Harness 示例 ==========

// 1. Event 類型定義
type HarnessEvent =
  | { type: "user_prompt"; content: string }
  | { type: "llm_delta"; token: string }
  | { type: "tool_call"; id: string; name: string; args: unknown }
  | { type: "tool_result"; id: string; result: unknown }
  | { type: "human_input_required"; prompt: string; schema: unknown };

// 2. Policy Engine
class PolicyEngine {
  private rules: PolicyRule[];

  check(toolName: string, args: unknown): "allow" | "ask" | "deny" {
    const rule = this.rules.find(r => r.matches(toolName, args));
    return rule?.decision ?? "deny"; // fail-closed
  }
}

// 3. Session Manager
class SessionManager {
  private sessions = new Map<string, Session>();

  create(): Session {
    const session: Session = {
      id: crypto.randomUUID(),
      state: "idle",
      history: [],
      createdAt: Date.now()
    };
    this.sessions.set(session.id, session);
    return session;
  }

  appendEvent(sessionId: string, event: HarnessEvent) {
    const session = this.sessions.get(sessionId);
    if (!session) throw new Error("Session not found");
    session.history.push(event);
  }
}

// 4. Tool Executor
class ToolExecutor {
  private registry = new Map<string, Tool>();

  register(tool: Tool) { this.registry.set(tool.name, tool); }

  async execute(call: { id: string; name: string; args: unknown },
                policy: PolicyEngine): Promise<unknown> {
    const decision = policy.check(call.name, call.args);
    if (decision === "deny") throw new Error(`Permission denied: ${call.name}`);
    if (decision === "ask") {
      // 發出 human_input_required 事件，等待審批
      await this.requestApproval(call);
    }

    const tool = this.registry.get(call.name);
    if (!tool) throw new Error(`Tool not found: ${call.name}`);

    return tool.execute(call.args);
  }
}

// 5. Agent Loop（核心迴圈）
class AgentLoop {
  constructor(
    private session: Session,
    private llm: LLMClient,
    private tools: ToolExecutor,
    private policy: PolicyEngine,
    private onEvent: (event: HarnessEvent) => void
  ) {}

  async run(prompt: string) {
    this.session.state = "running";
    this.onEvent({ type: "user_prompt", content: prompt });

    let messages = [...this.session.history];

    // Agent loop: 推理 → 工具呼叫 → 結果回饋 → 繼續推理
    while (true) {
      const response = await this.llm.chat(messages, {
        tools: this.tools.list(),
        stream: true
      });

      // 串流輸出
      for await (const chunk of response) {
        if (chunk.type === "delta") {
          this.onEvent({ type: "llm_delta", token: chunk.text });
        }
      }

      // 檢查是否有工具呼叫
      if (response.toolCalls.length === 0) break;

      for (const call of response.toolCalls) {
        this.onEvent({ type: "tool_call", ...call });

        try {
          const result = await this.tools.execute(call, this.policy);
          this.onEvent({ type: "tool_result", id: call.id, result });
          messages.push({ role: "tool", content: result });
        } catch (err) {
          messages.push({ role: "tool", content: `Error: ${err.message}` });
        }
      }
    }

    this.session.state = "completed";
  }
}

這個最小示例展示了 Harness 的核心邏輯：session 管理 + 事件驅動 + 權限控制 + 工具執行 + agent loop。生產級的 Harness 會在此基础上加入 MCP 整合、subagent orchestration、sandboxing、observability 等能力。

最佳實踐

設計可靠 Harness 的 10 個原則

1. Session-first，不是 completion-first — 把 agent 當成長期互動的 session，不是單次 API call
2. Side-effect aware — 每個工具呼叫都要標記副作用等級
3. Fail-closed permissions — 預設拒絕，明確允許才開放
4. Tool calls 必須結構化 — JSON Schema validation，不要裸字串
5. 所有重要事件可追蹤 — Event-sourced logs，支援 replay / debug
6. 支持 cancel / retry / resume — 長任務不能卡死
7. Agent 與 UI 分離 — 協議中介清晰，UI 換了 runtime 不用改
8. MCP/外部工具整合要經 policy proxy — 不要直接暴露給模型
9. 同一 session 的並發要可控 — Queue owner / single-writer model
10. 對 prompt injection 視為系統級威脅 — Untrusted content 要隔離上下文

常見陷阱與解法

測試策略

應測的層次：

1. Protocol tests — initialize、session create/load、prompt、cancel、config mutation、error mapping
2. Tool integration tests — schema validation、timeout、malformed output、partial failure
3. Security tests — path escape、command injection、prompt injection、approval bypass
4. Lifecycle tests — agent crash mid-turn、restart & resume、pending cancel
5. Concurrency tests — multiple prompt submissions、session lock contention、queue depth bounds

好的 debug 能力：raw event log、normalized + original error、lifecycle snapshot、tool call trace、permission decision trace。

安全與治理

企業級考量

企業級 Harness 不只是「讓 agent 會做事」，而是要讓 agent：

• 做對事（policy enforcement）
• 在對的權限下做（least privilege）
• 留下可審計紀錄（audit trail）
• 出錯時可收斂與回滾（rollback / replay）

安全模型

  flowchart TD
    IN[Agent Tool Call] --> PE{Policy Engine}
    PE -->|allow| SANDBOX[Sandbox Execution]
    PE -->|ask| HUMAN[Human Approval]
    PE -->|deny| REJECT[Rejected]
    HUMAN -->|approve| SANDBOX
    HUMAN -->|deny| REJECT
    SANDBOX --> RESULT[Result]
    RESULT --> LOG[Audit Log]
    RESULT --> CONTEXT[Context Update]

MCP 的安全挑戰

• MCP server 的 tool descriptions 可能是 untrusted
• 遠端 MCP server 的資料外洩風險
• Agent-to-agent communication 的身份與授權問題
• 跨租戶 memory leakage

未來趨勢

1. Harness 標準化

• MCP 正在標準化 tool/resource/prompt 接口，已成為 de facto ecosystem center
• ACP 正在成形，標準化 agent session control
• 未來格局：MCP = 能力平面，ACP = 控制平面

2. 多模態 Harness

未來 Harness 不只管文字與 shell，還會統一管理：

• Vision tools
• Browser automation
• GUI control
• Voice I/O
• Video / sensor inputs

3. 分布式 Agent Harness

• Remote workers
• Distributed session routing
• Agent mesh / fabric
• Policy-enforced org-wide orchestration
• Cross-device persistent sessions

4. Policy-native Agent Runtime

未來的 Harness 會越來越像：

• Mini OS（資源管理、行程管理）
• Zero-trust runtime（每個操作都要驗證）
• Auditable automation layer（所有操作可追溯）

重點整理

• Harness 是 agent 系統的控制平面，不是附屬品 — 它決定了 agent 是否安全、可靠、可觀測
• Agent = Model + Harness — 模型是引擎，harness 是底盤，缺一不可
• 七個核心模組：Session Manager、Message Router、Tool Executor、Permission Layer、Context & Memory、Transport Adapters、Orchestrator
• MCP 解決能力接入；ACP 解決 agent session 控制 — 兩者互補
• 權限必須是硬邏輯層 — 不能只靠 prompt 裡的一句話
• 真正的競爭點在 Harness 品質 — 模型能力的差距在縮小，harness 工程的差距在拉大

參考資料

• OpenAI — Harness Engineering: Leveraging Codex in an Agent-First World
• Martin Fowler — Harness Engineering for Coding Agent Users
• LangChain — The Anatomy of an Agent Harness
• Agent Engineering — Harness Engineering in 2026
• Agent Client Protocol
• BeeAI ACP
• MCP 2026 Roadmap
• Thoughtworks — The Model Context Protocol’s Impact on 2025
• Cerbos — AI Agents, MCP, and Authorization Guardrails
• Microblink — What is ACP Agent Communication Protocol
• OpenAI Codex CLI (GitHub)
• Anthropic Claude Code Docs