如何打造 AI Agent Harness

這篇教你把 AI Agent 的模型、工具、驗證和狀態包進一個可控的 harness，做出可測試、可重試、可擴充的代理流程。

這篇給想超越 prompt tuning 的開發者看。照著做完，你會得到一個可運作的 agent harness 藍圖，知道模型負責什麼、控制層負責什麼，還能把每一步驗收清楚。

核心觀念很單純：Agent 不是只有模型，而是模型外面再包一層 harness，去決定它看得到什麼、能做什麼、結果怎麼驗證。這種切法會讓除錯更直接，也更適合放進正式環境。

開始之前

• OpenAI 或 Anthropic 帳號，並準備好有效 API key。
• Node 20+ 或 Python 3.11+。
• Git 2.40+。
• 終端機與程式編輯器。
• 熟悉 JSON、HTTP request、function calling。
• 可選：OpenAI 文件與OpenAI GitHub repo，或你選用模型供應商的對應文件與 SDK。

Step 1: 定義 Agent 邊界

目的：先把模型和 harness 分開，之後才有辦法獨立調整行為、除錯與權限。

請先寫出三個區塊：環境輸入、harness 規則、模型輸出。這一步的具名產出是「邊界圖」。

Environment -> Harness -> Model -> Harness -> Tools/Checks -> Final Output

驗收：你應該能用一句話說出哪個元件可以呼叫 API、哪個元件負責記憶、哪個元件決定結果能不能放行。如果說不清楚，邊界還不夠明確。

Step 2: 設計 Observation Schema

目的：控制模型每一輪能看見什麼，避免把一大坨原始對話直接丟給它。

請把輸入整理成固定 JSON。這一步的具名產出是「Observation Schema」。

{
  "goal": "summarize invoice",
  "messages": ["..."],
  "tool_results": [],
  "constraints": ["no PII", "return JSON"]
}

驗收：你應該看到每一輪都用同一組 key，即使 value 改變也不會亂掉。這代表 harness 已經在控制觀測，而不是讓 prompt 自己長大。

Step 3: 註冊 Allowed Actions

目的：限制 agent 能做的事，只留下可審核、可映射到真實 API 的動作。

請建立工具登錄表，列出名稱、輸入格式、權限規則。這一步的具名產出是「Tool Registry」。

tools:
  - name: search_docs
    input: { query: string }
  - name: fetch_record
    input: { id: string }
  - name: submit_answer
    input: { text: string }

驗收：你應該能拒絕任何不在登錄表中的 action。若模型要求不存在的工具，harness 要回傳受控錯誤，而不是直接執行。

Step 4: 加入 Validation 與 Retry

目的：在結果被接受前先檢查結構、政策與任務規則，避免第一個答案就直接進入系統。

請實作驗證流程，包含 JSON 格式、禁用內容、任務條件，然後把失敗原因回灌給模型重試。這一步的具名產出是「Validation Pipeline」。

if !valid_json(output) or !passes_policy(output) {
  retry_with_error_context();
}

驗收：你應該看到 malformed response 變少，且失敗不再默默吞掉。最好同時記錄 accepted 與 rejected，方便之後做回歸測試。

Step 5: 建立 State 與 Memory

目的：只保留對任務有用的狀態，避免把整段聊天史都當成記憶。

請把持久狀態和暫時上下文分開，並且只在驗證通過後更新。這一步的具名產出是「Session State」。

驗收：你應該看到 agent 在多輪互動下行為更穩定，因為狀態由 harness 接手，不再靠模型自己重建背景。到這裡，你已經有一個基本公式：模型負責推理，harness 負責控制。

常見錯誤

• 把所有工作都丟給 prompt。 修法：把工具選擇、schema 檢查、重試流程移到 harness，prompt 只保留推理所需資訊。
• 給模型太多上下文。 修法：改用精簡的 observation schema，並在每輪前摘要舊狀態。
• 直接相信第一次輸出。 修法：先驗證結構與政策，再決定接受、重試或升級處理。

接下來可以看什麼

如果這個 harness 已經跑起來，下一步可以加 evaluation scripts、tracing、sandboxed tool execution，讓你能持續量測可靠度，並把 agent 推進到 production 等級。