# 什麼是 harness engineering？為什麼你應該在意？

> 📖 本站完整內容索引（documentation index）：[llms.txt](/llms.txt)

> 原作者：Google Cloud Tech (@GoogleCloudTech) · 策展與摘要：EasyVibeCoding · 平台：X (Twitter) · 熱度：🔥🔥🔥🔥 · 日期：2026-08-25

> 原始來源：https://x.com/GoogleCloudTech/status/2091986652595950079

## 證據與延伸閱讀

- [# 什麼是 harness engineering？為什麼你應該在意？](https://pub-75d4fe1e4e80421b9ecb1245a7ae0d1a.r2.dev/curated/15d68451c9cd0734.jpg)
- [ADK 2.0工作流程與終止機制](https://pub-75d4fe1e4e80421b9ecb1245a7ae0d1a.r2.dev/curated/29f758e70c5d4cbb.jpg)

## 中文摘要

# 什麼是 harness engineering？為什麼你應該在意？

要如何在完全沒有手動撰寫任何程式碼的情況下，交付一個軟體產品？

今天有位朋友問了我這個問題，我才發現自己沒有一個簡單的答案。所以我進一步深入研究。

結果發現，答案就在於你如何設計 harness。

作者：@shirmeir86

等等，現在是怎樣？什麼是 harness engineering？

這之所以成為目前 coding agent 領域最重要的趨勢，是有原因的。現今最大的問題是：如何在不用逐行閱讀的情況下，驗證 AI 產生的程式碼？要怎麼確保 Agent 不會弄壞正式環境，或刪除你的資料？

我最近讀到一個很有意思的實驗：一個由 3 位工程師組成的團隊，在完全沒有手動撰寫任何程式碼的情況下，建立並發布了一個軟體產品的內部 beta 版本。每一行程式碼——應用程式邏輯、測試、CI 設定、文件、可觀測性，以及內部工具——全部都是由 Codex 撰寫的。

他們是怎麼做到的？他們沒有撰寫應用程式，而是設計了 harness。

## harness 究竟是什麼？

把 AI Agent 想成一匹強大的賽馬。harness 就是賽道、眼罩，以及騎師手中的韁繩，讓它朝正確的方向前進，而不是跳進觀眾席。

正如我的同事 Arthur Thompson 今天所說：對 Agent 而言，harness 是由所有包覆 LLM 的確定性元件組成。

Balaji Subramaniam 在他的部落格中詳細介紹了這些確定性元件——協調層、執行沙盒、狀態持久化，以及驗證工具。

如果你想建立可靠的 agentic 系統，你的工作重心就會從撰寫邏輯，轉變為設計環境。以下是你需要專注的幾件事：

1. 設定嚴格的界線：不要讓 Agent 猜測自己可以碰哪些東西。強制套用嚴格的存取規則（例如把它限制在特定沙盒內），避免它不小心清除正式環境中的資料。

1. 建立「Repair Loop」：Agent 遲早會犯錯。一個優秀的 harness 會自動捕捉錯誤，例如建置失敗或測試失敗，然後把乾淨的日誌直接回傳給 Agent，讓它自行修正程式碼。

1. 給它地圖，而不是操作手冊：正如 OpenAI 團隊所發現的，不要用大量的指示文件淹沒 Agent。應該有邏輯地組織程式庫，讓 Agent 在工作過程中逐步自行探索所需的 context。

## 讓我看看程式碼

實務上會長什麼樣子？以下是一個使用 Google Antigravity SDK 搭配 Google 的 ADK，設定本機 harness 的簡單範例。請注意，我們嚴格將 Agent 限制在特定的 workspace（`workspaces=[“./sandbox”]`）中，並提供儲存記憶的位置（`save_dir=”./trajectories”`），讓它能從過去的經驗中學習。

```python
import os
from google.adk.labs.antigravity import AntigravityAgent
from google.antigravity import LocalAgentConfig
from google.antigravity.hooks import policy

# Ensure absolute paths for workspace containment
sandbox_dir = os.path.abspath("./sandbox")
os.makedirs(sandbox_dir, exist_ok=True)
save_dir = os.path.abspath("./trajectories")

# 1. Engineer the harness environment
sdk_config = LocalAgentConfig(
    system_instructions="You are a helpful local environment assistant.",
    workspaces=[sandbox_dir],
    # Let the agent write safely within the restricted sandbox boundary
    policies=[policy.allow_all()], 
    save_dir=save_dir,
)

# 2. Wrap the config to run the agent inside the harness
root_agent = AntigravityAgent(
    name="antigravity_assistant",
    description="Runs an Antigravity SDK agent inside ADK.",
    config=sdk_config,
)
```

![說明 AI Agent 存取控制權限與 sandbox 隔離機制的架構圖](https://pub-75d4fe1e4e80421b9ecb1245a7ae0d1a.r2.dev/curated/15d68451c9cd0734.jpg)
> 說明 AI Agent 權限控管機制的架構圖，左側為藍色的 AI Agent，右側上方以綠色框顯示可寫入的 ./sandbox folder，中間與下方則以虛線及紅色框顯示遭到政策阻擋的 Production Database 與 Host System Files。

<details class="chart-data"><summary>展開畫面重點</summary><div class="me-note">- 圓形節點「AI Agent」
- 實線箭頭連接至綠色長方形「./sandbox folder」，上方標籤為「Writes Code」
- 虛線箭頭連接至紅色圓柱體「Production Database」，上方標籤為「Blocked by policy」
- 虛線箭頭連接至紅色長方形「Host System Files」，上方標籤為「Blocked by policy」</div></details>

完成這樣的設計後，你可以把既有程式碼放進沙盒，寫一個簡單的迴圈對它執行單元測試，接著讓 Agent 反覆修正自己的錯誤。

## 加入測試

那麼，我們實際上要如何對這個受沙盒限制的 Agent 執行測試？

在現代的 harness engineering 中，測試是 Agent 工作流程圖中的主動元件。使用 Google 的 ADK 2.0——它引入了以圖為基礎的工作流程——你可以把測試驗證步驟定義成一個簡單的路由節點。

如果測試通過，工作就完成了。如果測試失敗，harness 會自動把錯誤回傳給 Agent，讓它再試一次。請注意內建的「kill switch」：我們會追蹤迭代次數，因此如果 Agent 卡在不斷弄壞、修正程式碼的無限迴圈中，harness 就能安全地中止執行。

```python
from google.adk.agents.context import Context
from google.adk import Event
from google.adk.events.event_actions import EventActions
from google.genai import types

# 3. Evaluate the code in the sandbox
def execution_test_node(ctx: Context):
    # Safely track our attempts to prevent infinite loops
    iteration_count = ctx.state.get("iteration_count", 0) + 1
    ctx.state["iteration_count"] = iteration_count
    
    test_passed = ctx.state.get("test_passed", False)
    feedback = ctx.state.get("feedback", "")
    
    if test_passed:
        # Success! End the workflow.
        return Event(actions=EventActions(route="END"))
        
    if iteration_count > 5:
        # The Kill Switch: The agent is stuck. Stop the loop.
        return Event(actions=EventActions(route="END"))
    
    # Failure! Feed the error trace back to the agent and loop it.
    feedback_msg = f"The unit tests failed with the following traceback:\n\n{feedback}"
    
    return Event(
        content=types.Content(role="user", parts=[types.Part(text=feedback_msg)]),
        actions=EventActions(route="loop_back")
    )
```

如果你想看看這種測試路由模式的實際運作方式，可以參考 Balaji 的 ADK harness 程式庫，其中提供了完整的實作範例。

## 使用以圖為基礎的工作流程串起所有元件

要連接 Agent 和測試節點，你可以使用 Workflow 圖，清楚描繪執行流程，而不需要撰寫複雜、巢狀的 Python `while` 迴圈。

可以把它想成是在賽道上畫出實際的行車線：

```python
from google.adk import Workflow

# 4. Wire the agent and the test node together into a loop
repair_loop = Workflow(
    name="repair_loop",
    edges=[
        # 1st Step: Define the main sequence (START -> agent -> test node)
        ("START", root_agent, execution_test_node),
        
        # 2nd Step: If the test returns "loop_back", go back to the agent
        (execution_test_node, {"loop_back": root_agent})
    ]
)
Press enter or click to view image in full size

```

![包含 root_agent 與 execution_test_node 節點的 Agent loop 流程圖](https://pub-75d4fe1e4e80421b9ecb1245a7ae0d1a.r2.dev/curated/29f758e70c5d4cbb.jpg)
> 展示 AI agent 執行流程的狀態圖，由左至右包含綠色的 START 起點、藍色的 root_agent 節點、紅色的 execution_test_node 菱形節點，以及綠色的 END 終點，節點之間透過帶有 route 條件的箭頭相連，並包含從測試節點返回 root_agent 的 loop_back 回圈。

<details class="chart-data"><summary>展開畫面重點</summary><div class="me-note">- 綠色圓形節點標籤：`START`
- 藍色矩形節點：
  - `root_agent`
  - `Writes Code`
- 紅色菱形節點：
  - `execution_test_node`
  - `Runs unit tests`
- 連線與路由標籤：
  - 從 `START` 連線至 `root_agent`
  - 從 `root_agent` 連線至 `execution_test_node`
  - 從 `execution_test_node` 連線回 `root_agent`，標籤為 `route='loop_back'`
  - 從 `execution_test_node` 連線至 `END`，標籤為 `route='END'`
- 綠色圓形節點標籤：`END`</div></details>

恭喜！你已經建立了一個自主系統。Agent 撰寫程式碼，然後將程式碼交給測試節點。如果測試失敗並回傳 `loop_back` 路由，Agent 就會帶著錯誤日誌再試一次。

你可以在 ADK samples 中查看更多迴圈模式的範例。

## 親自試試看

你可能會想，為什麼需要用 Python 腳本來執行 Agent？在一般的聊天視窗中，你就是 harness：你負責複製錯誤日誌，並在旁邊盯著模型。軟體 harness 則能讓系統自行照看自己，讓你可以完整自動化測試驅動的程式開發，或安全地重構大型既有程式庫。

如果你今天就想在自己的電腦上執行這個自我修復迴圈，整個設定過程不到五分鐘：

1. 安裝 framework：在終端機執行 `pip install “google-adk[antigravity]”`，取得開放原始碼的 Agent Development Kit 和 Antigravity 整合。

1. 設定 API key：從 Google AI Studio 取得免費的 Gemini API key，並將它匯出到你的環境中（`export GEMINI_API_KEY=”your-key”`）。

1. 執行迴圈：將上面的程式碼區塊儲存為 Python 腳本，把一個有問題的 Python 或 Node 檔案放進新建立的 `./sandbox` 資料夾，然後執行腳本。

1. 擴充你的圖：單元測試只是基礎。若要讓 harness 更加穩固，可以在工作流程中加入第二個 AI Agent，例如 `SecurityAuditor`，在程式碼通過前進行檢查；也可以接入自訂 linter，強制遵守嚴格的架構規則。

接下來，你可以把簡單的測試節點替換成真正會對沙盒執行 `pytest` 或 `npm test` 的 subprocess，這樣就會得到一個完整運作的 Repair Loop。

如果你準備好擴大規模，可以在 antigravity.google 下載完整的 IDE 和 CLI，探索用於遠端執行的 Antigravity managed agent，以及用來執行以圖為基礎工作流程的 Google ADK 2.0。

## 延伸閱讀

我在 Google 的同事整理了一些很棒的指南，介紹接下來可以往哪些方向發展。若你想了解如何為 Agent 建立安全環境，可以參考 Sara 展示 Cloud Run 沙盒的 codelab。若你想精通自我修正，Balaji Subramaniam 最近發表了一篇深入探討 Coding Agent Loop Engineering 的文章。若想看看這些方法如何應用在大規模企業使用情境，則可以閱讀 James O’Reilly 對「使用 agentic pipeline 和 Antigravity 大規模自動化既有系統現代化」的解析。

## 標籤

Harness, Agent, 產業趨勢, OpenAI