Harness 理論篇 Part 03｜Agent Loop 與控制流：模型如何真正開始工作？

模型回傳一個結構化 Tool Call，只代表它提出了一個候選操作。

接下來還有一串不能交給運氣的工作：工具是否仍存在、參數能不能被安全解析、目前身份是否有權執行、工具實際跑在哪裡、結果如何和原始請求配對、失敗後是否值得重試，以及模型不再呼叫工具時，任務究竟是完成、受阻，還是在等待外部事件。

這些責任合在一起，才形成 Agent Loop。

最小流程看起來很短：

Input → Model → Tool Request → Tool Result → Model → Completion

真正的工程難度藏在箭頭裡。任何一段缺少明確的 Authority、State Transition 或 Protocol Contract，Loop 仍然可能在 Demo 裡跑起來，卻很難可靠地暫停、恢復、取消或證明完成。

OpenAI 將 Agent Loop 描述為協調使用者、模型與工具互動的核心邏輯。Anthropic 的 Tool Use 文件也把 Tool Use 定義成應用程式與模型之間的 Contract：模型提出結構化請求，應用程式或服務端執行操作，再把結果送回對話。模型本身不會因為輸出一段 JSON 就完成外部操作。¹²

Agent Loop State Machine

Figure 3-1｜可靠的 Agent Loop 是受治理的 State Machine：模型提出候選行動，Harness 負責解析、授權、執行、記錄與明確終止。

Tool Calling 提供介面，Agent Loop 承擔控制

Tool Calling 通常提供兩件事：

把可用操作與 Input Schema 告訴模型。
讓模型回傳結構化的 Tool Request。

以查詢訂單為例，模型可能回傳：

{
 "tool_name": "get_order",
 "arguments": {
 "order_id": "ORD-1042"
 }
}

這段 JSON 沒有證明：

ORD-1042 屬於目前 User 或 Tenant
get_order 仍是模型看到的相同版本
Arguments 已完成解析、Canonicalization 與 Schema Check
這次操作已通過 Policy
工具真的執行成功
Result 沒有洩漏其他 Tenant 的資料
這次查詢足以滿足 Task Contract

模型通常只擁有提出候選下一步的權力。Harness 要把 Proposal 轉成一個受控的 State Transition：解析實際 Response Items、固定 Tool 與 Arguments、重新授權、執行、記錄 Result，最後再決定是否繼續。

這個分工也適用於 Server-executed Tool。即使工具由模型供應商代為執行，產品端仍要說清楚哪些 Tool Policy 與 Execution Evidence 由供應商負責，哪些 Identity、Tenant Boundary、Task Contract 與 Completion Gate 仍由自己的 Harness 承擔。

一個受控 Agent Loop 的八個階段

不同 Framework 會使用不同類別與函式名稱，但責任順序可以整理成八個階段：

階段	Harness 的責任	主要輸出
1. Assemble Context	根據 Task Contract、Run State、Policy 與可見 Capabilities 組裝本輪輸入	Bounded Model Context
2. Infer Next Action	呼叫模型，取得文字、Tool Request、Plan Update、Question 或 Wait Proposal	Typed Response Items
3. Parse and Canonicalise	解析實際 Blocks，解析 Tool Version，固定 Arguments 與 Resource Identity	Canonical Proposal
4. Authorise Transition	根據 Actor、Tenant、Scope、Policy、Risk 與 State Version 決定是否允許	Grant、Deny 或 Approval Required
5. Execute in Boundary	在 Sandbox、Timeout、Cancellation 與其他邊界內執行 Capability	Typed Execution Outcome
6. Commit Correlated Observation	將 Request、Result、Operation ID、Evidence 與 State Transition 一起記錄	Updated Canonical Run State
7. Evaluate Terminal Candidate	若沒有可執行 Request，檢查 Contract、Evidence、Pending Work 與 Completion Gate	Continue、Wait、Accept 或 Reject
8. Continue, Wait or Terminate	明確選擇下一輪、暫停、修復、取消、失敗或完成	Explicit Run Status and Reason

這裡只定位每個責任，完整 Context 組裝留到 Part 04，Tool Execution Lifecycle 留到 Part 05，Durable State 與 Checkpoint 留到 Part 06。

解析和授權為什麼要分開？

Harness 必須先把模型輸出的字串解析成唯一、可比較的操作，Policy 才知道自己正在批准什麼。

例如模型要求寫入：

./exports/../payments/config.json

系統若直接對原始字串做路徑檢查，後續 File API Canonicalize 後可能指向另一個 Resource。比較安全的順序是：

Parse structure
→ Resolve tool and version
→ Canonicalise arguments and resources
→ Authorise the canonical operation
→ Apply pre-execution gates
→ Execute

這不代表所有 Business Validation 都必須在 Authorisation 前完成。重點是 Policy 決策和實際執行必須作用在同一個 Canonical Operation 上。

Dynamic Tool Catalog 也需要版本一致性。若模型看到 deploy_service@v2，Runtime 卻在執行前把它解析成語意不同的 v3，這次 Proposal 應被視為 Stale，而不是悄悄換成另一個 Tool。

執行結果不能只有 Success 和 Error

Execution Outcome 至少要能區分：

success
validation_failed
permission_denied
approval_required
timeout
cancelled
background_accepted
unknown_outcome
unknown_or_disabled_tool

這些不是錯誤訊息的不同文案，而是 Controller 會採取不同 Transition 的 Protocol State。

例如 timeout 不一定代表外部 Side Effect 沒有發生。若付款 API 已收件，但 Response 在回程遺失，下一步應先 Reconcile Operation ID，而不是直接重送。完整的 Idempotency 與 Recovery 會留到 Part 08。

一小段 `while` 能說明多少？

下面是一段架構級 Pseudocode：

while budget.allows(run):
 context = context_builder.build(run)
 response = model_adapter.generate(
 context=context,
 tools=capability_view.for_run(run),
 )

 items = protocol.parse_items(response)
 requests = protocol.executable_requests(items)

 if requests:
 for request in execution_policy.order(requests, run):
 operation = capability_registry.canonicalise(request, run)
 decision = policy.authorise(operation, run)

 if decision.requires_approval:
 result = approval_gateway.pause_for_decision(operation, run)
 elif decision.denied:
 result = tool_results.denied(operation, decision)
 else:
 result = capability_runtime.execute(operation, decision.grant)

 run = run_store.commit_correlated_result(
 run=run,
 request=request,
 operation=operation,
 result=result,
 )
 continue

 decision = completion_gate.evaluate(
 terminal_candidate=items,
 run=run,
 )
 run = run_store.commit_decision(run, decision)

 if decision.accepted:
 return delivery.from_committed_run(run)
 if decision.waiting:
 return delivery.waiting_receipt(run)

 run = controller.repair_replan_or_stop(run, decision)

raise BudgetExceeded(run.stop_reason)

這段可以說明

模型提出 Request，Harness 授權與執行。
Tool Resolution、Canonicalization 與 Policy Decision 是獨立步驟。
每個 Request 都要提交一個可關聯的 Terminal Result。
一般文字輸出只是 Terminal Candidate。
Completion、Waiting、Repair 與 Budget Stop 是不同 Transition。
Delivery 來自已提交的 Run State。

這段不能證明

Authentication、Tenant Isolation、Credential Binding 已正確實作。
多個 Tool Request 可以安全 Parallel Execute。
Side Effect 已具備 Idempotency、Compensation 與 Unknown-outcome Reconciliation。
Distributed Lock、Worker Crash 與 Checkpoint Recovery 已處理。
Approval Expiry、Reconnect、Protocol Versioning 已完整。
Completion Gate 或 Model-based Evaluator 已經可靠。
這段示意程式可以直接進 Production。

一段會循環的 Code 只證明控制流能繼續走。它不會自動獲得安全、可靠性與品質保證。

四個不能破壞的 Loop Invariants

Invariant 1：以實際 Response Items 與 Execution Facts 為準

模型供應商可能提供 stop_reason、Finish Status 或其他方便欄位。這些欄位是 Provider Contract 的一部分，卻不應取代對實際 Response Items 的解析。

Harness 要避免兩類錯誤：

Response 內仍有 Tool Request、Partial Item 或 Pending Control Item，Controller 卻因 Stop Signal 直接結束。
Tool Outcome 仍是 Unknown，Transcript 卻因預期流程把它寫成 Success。

控制系統不能用「應該發生」覆蓋「實際發生」。Provider Signal、Typed Content 與 Runtime Evidence 若互相衝突，系統應進入可診斷的 Protocol Error 或 Reconciliation Path。

Invariant 2：每個 Tool Request 有一個且只有一個 Terminal Result

這裡的「一個 Result」指 Protocol 層的 Terminal Disposition。執行過程可以有 Progress Event、Log Delta 或 Heartbeat，但每個 Tool Request 最終只能得到一個可關聯的 Terminal Result，例如：

success
denied
validation failed
timeout
cancelled
background accepted
unknown tool
unknown outcome

Tool Request and Result Integrity

Figure 3-2｜Progress Event 可以有很多個，但每個 Tool Request 只能有一個 Terminal Result；背景完成使用獨立 Work ID 與 Completion Event。

Background Work 是最容易弄亂這條規則的場景：

原始 Tool Request 得到 background_accepted Result。
Result 建立一個獨立 work_id。
Worker 透過 Progress Event 回報中間狀態。
背景完成後送出新的 Completion Event。
Completion Event 關聯 work_id，不偽裝成原 Request 的第二個 Tool Result。

一輪若有多個 Tool Request，每個 Request 都要有獨立 ID 與 Result。是否 Sequential 或 Parallel 必須由 Execution Policy 明確決定，不能因為 Response 裡同時出現三個 Call，就假設它們互不依賴。

Parallel Execution 至少需要知道：

Operation 是否互相獨立
Result 順序是否影響下一輪 Context
是否競爭同一 Workspace 或 Resource
其中一項失敗時，其他 Operation 要繼續、取消還是補償

Compaction、Replay 與 Context Assembly 也不能拆散 Request／Result Pair。缺少 Result 或出現 Duplicate Result，後續模型、Debug 與 Evaluation 都會對實際發生的事情產生不同解讀。

Invariant 3：Runtime State 不只存在 Transcript

Transcript 適合保存模型可見的對話與 Items，但以下資訊不能只靠聊天文字維持：

Approval Grant、Deny 與 Expiry
Tool Request／Result Receipt
Current State Version
Task Ownership
Active Background Work
Cancellation State
Budget Usage
Workspace Identity
Side-effect Operation ID
Scheduled Trigger
Last Acknowledged Event Sequence

例如 Tool 已經成功發出付款請求，Response 在網路中斷時遺失。Transcript 可能只看見 Timeout，但 Runtime 不能因此假設付款沒有發生。

Part 06 會完整處理 Run State、Checkpoint 與 Persistence。這裡先固定一條邊界：模型看得到的歷史，不等於系統必須保存的全部狀態。

Invariant 4：Continue、Wait 與 Terminate 都需要明確原因

「沒有 Tool Call」只代表模型產生了 Terminal Candidate，不能直接推導成成功。

Controller 還要考慮：

Task Contract 與 Required Evidence 是否滿足
是否有 Pending Approval、Background Work 或 External Event
Max Steps、Tool Calls、Retry、Token、Cost 與 Deadline
Human Cancellation
Non-recoverable Failure
Policy Stop
Loop Detection
Completion Gate 的 Accept／Reject

Approval Resolution 也不必然是 Terminal State。allow 可能讓原 Operation 繼續；deny 可能讓 Agent 改採其他方案、等待使用者修改 Contract，或直接停止。

每次暫停或終止都應保存 Explicit Reason。以下狀態不能只當成同一個 done 的不同文案：

completed
waiting_for_approval
waiting_for_external_event
cancelled
budget_exhausted
policy_stopped
failed

Workflow、Agent、Orchestration 與 Query Planning 不在同一個決策範圍

這四個詞常被混在一起，最後所有控制邏輯都被叫成 Agent。

Workflow, Agent, Orchestration and Query Planning

Figure 3-3｜Orchestration 處理跨步驟與資源協調；Workflow 與 Agent 是兩種控制模式；Query Planning 只處理 RAG 內的檢索決策。

概念	擁有的主要決策	常見特徵
Workflow	已知路徑中的步驟與 Transition	Predictable、容易測試、適合穩定流程
Agent	在允許範圍內動態選擇下一步與工具	Flexible、路徑不固定、需要更強控制
Orchestration	誰執行、資源如何分配、Handoff 與 Failure 往哪走	Routing、Scheduling、Ownership、Stop
Query Planning	查什麼、如何 Rewrite／Decompose、選哪個 Index	RAG 子系統內的檢索決策

Anthropic 把 Workflow 定義為由預先設計的 Code Path 協調模型與工具，Agent 則由模型動態主導流程與工具使用，並建議優先採用能完成需求的最簡單方案。Agentic System 通常用更高的 Cost 與 Latency 換取彈性。³

Orchestration 常常會協調 Workflow 或 Agent，但不是所有實作都必須把它做成一個包住其他元件的外層服務。它是一組跨步驟、資源與 Ownership 的責任，可以和 Controller 存在同一 Process，也可以由更外層系統承擔。

一個實用原則是 Deterministic First。

適合固定在程式中的決策包括：

Authentication 與 Tenant Scope
Hard Policy
Schema 與 Protocol Validation
Required Verification Sequence
Payment、Deployment 或 Deletion Gate
Budget Accounting

適合讓模型判斷的部分包括：

在多個已授權工具中選擇下一步
根據 Observation 修改 Plan
無法事先列舉的探索順序
需要語意理解的分類、Rewrite 或 Decomposition

把固定 Transition 全部交給模型，不會自然增加智慧，只會把可測試的程式邏輯換成較昂貴且較不穩定的決策。

Query Planning 的範圍也要守住。把問題拆成 Sub-query、選擇 Index 並合併 Evidence，仍然是 Retrieval Decision。它不擁有整個任務的 Workspace、Approval、Tool Execution、Completion Authority 或 Recovery。

Item、Turn、Thread：把 Agent Interaction 拆成可持久化的生命週期

一般聊天 API 容易讓人把互動理解成一個 Request 對一個 Response。Agent 工作常常不是這種形狀。

一次「跑測試並修正失敗」可能產生：

User Message
Plan Update
Tool Request
Approval Request
Tool Execution
Streamed Log
Diff
Verification Result
Final Agent Message

OpenAI 的 Codex App Server 將這類互動拆成 Item、Turn 與 Thread，並使用雙向 JSON-RPC Protocol 處理 Event、Approval 與 Client Integration。這是 Codex 的具體實作，不是所有產品必須照抄的通用標準；可泛化的是它背後的要求：Typed Event、巢狀生命週期、穩定 ID、Server-side State 與 Reconnect。⁴

Thread, Turn and Item Lifecycle

Figure 3-4｜Thread 保存多個 Turn；Turn 由有序 Typed Items 組成。需要批准的 Operation 必須先暫停，再依 Client Decision 執行或拒絕。

Item：最小的 Typed Unit

Item 可以是：

User Message
Agent Message
Plan Update
Tool Request
Approval Request
Tool Execution
Tool Result
Diff
Artifact Reference

典型 Lifecycle：

item/started
→ optional item/delta or progress
→ item/completed | item/failed | item/cancelled

不同 Item 不必擁有完全相同的 State。Message 可以 Streaming Delta，Approval Request 則需要 Pending、Resolved、Expired 等語意。Protocol 應保留 Type-specific Payload，而不是把所有事情壓成一段文字。

Turn：一段可暫停的 Agent Work

Turn 由一次 User Input 或 External Trigger 啟動，可以包含多次 Model Inference、Tool Request 與 Tool Result。

turn/started
→ ordered typed items
→ turn/completed
 | turn/waiting
 | turn/failed
 | turn/cancelled

Turn 不等於一次模型 API Call。它可以在 Model 與 Tool 之間循環多次，也可以暫停等待批准或外部事件。

Thread：跨 Turn 的 Durable Container

Thread 包含多個 Turn，可以被 Create、Resume、Fork、Archive、Reconnect 或 Replay。

Thread History 應讓新的 Client Session 取得 Snapshot、Missing Events、Active Turn 與 Pending Approvals。瀏覽器關閉只代表顯示介面離開，不應把 Runtime State 一起刪掉。

Streaming、Approval 與 Reconnect 需要雙向控制

Agent UI 不只是逐 Token 顯示模型文字。

Server 可能持續推送：

Item Lifecycle Event
Tool Progress
Log Delta
Artifact Reference
Budget Warning
Verification Result
Turn State Change

Server 也可能主動向 Client 發出 Approval Request：

server: approval/requested
 approval_id = apr_31
 operation_id = op_88
 state_version = 14
 reason = "Deploy to production"
 expires_at = ...

client: approval/resolved
 approval_id = apr_31
 decision = deny

正確順序是：

Proposed Operation
→ Approval Required
→ Turn enters waiting
→ Client allow / deny / expiry
→ Allow: execute the authorised operation
→ Deny or expiry: emit a terminal denied result, then replan or stop

Tool Execution 不能在 Approval 之前被畫成已經開始。批准也不能只寫「讓 Agent 繼續」，至少應綁定：

Approval ID
Operation ID
Canonical Arguments
Actor 與 Scope
Policy / State Version
Reason
Expiry
Decision

State Version 很重要。若等待批准期間 Workspace、Arguments 或 Policy 已改變，舊批准不應自動套用到新的 Operation。

Reconnect 也屬於 Control Flow。Client 提供 Last Acknowledged Sequence，Server 回傳 Thread Snapshot、Missing Event Replay、Active Turn Status 與 Pending Approvals。Client 不應重新上傳整段聊天，再要求 Server 猜測現在執行到哪裡。OpenAI App Server 同樣使用 Server-side Thread State 與 Event History，讓不同 Client 能呈現一致 Timeline。⁴

Stop Policy：Agent 需要停止條件，也需要合法的等待狀態

Agent Loop 應在開始前取得 Budget 與 Stop Policy。

限制	防止的問題	觸發後可能的 Transition
Max Steps / Turns	無界規劃與反覆推理	Replan、Escalate 或 `budget_exhausted`
Max Tool Calls	重複探索或 Tool Storm	Stop、縮小 Capability 或 Human Review
Retry Budget	同一 Failure 無限重試	Fallback、Reconcile 或 Fail
Token Budget	Context 與 Output 失控	Compact、Degrade 或 Stop
Cost Budget	任務成本超過授權	Approval 或 Terminate
Wall-clock Deadline	Worker 長時間占用資源	Checkpoint、Cancel 或 Reassign
Loop Detection	相同行動沒有新增 Evidence	Replan、Rollback 或 Escalate
Human Cancellation	使用者撤回工作	Cancel Pending Work and Persist
Policy Stop	觸碰禁止範圍	Deny、Wait 或 Terminate

Runtime 必須實際計數與執行限制，不能只把 Budget 寫進 Prompt。

等待人類批准、Webhook、Background Work 或排程時間，不等於 Failure。系統應持久化 waiting_reason 與 Resume Trigger，釋放不必要資源，而不是靠 Busy Polling 持續燒 Token。

Goal Drift：先分清楚漂移和正式變更

長任務會累積 Observation、Error、臨時修法與支線。Agent 可能一直有輸出，卻逐漸偏離 Task Contract。

常見漂移包括：

目標遺忘：原始 Acceptance Criteria 被長 Context 淹沒。
目標替代：把建立工具、重構模組或寫報告當成最終任務。
範圍蠕變：自行加入未授權的改善項目。
重複迴圈：反覆呼叫相同工具，沒有新增 Evidence。
局部最佳化：改善局部指標，卻破壞整體任務。

但不是每次目標改變都叫 Drift。使用者可以合法修改 Scope 或 Acceptance Criteria；這應形成新的 Contract Version、State Transition 與必要的 Re-authorisation，而不是悄悄覆寫原始目標。

偵測 Drift 不能只靠文字相似度。更有用的訊號包括：

Contract 還有哪些未滿足條件
Milestone 與 Evidence 是否增加
Tool Call 與 Failure Pattern 是否重複
Cost、Time、Step 與 Retry 的消耗
新工作是否落在 Allowed Scope
Completion Gate 是否重複回報同類缺口
Human 或 Monitoring Interrupt

修正可以逐步加強：

重新呈現 Goal、Scope 與 Acceptance Criteria。
產生目前 Progress、Gap 與下一個最小步驟。
在保留已驗證 Evidence 的前提下 Replan。
回復到安全 Checkpoint。
縮小 Tool、Data 或 Budget 範圍。
暫停，要求人類選擇繼續、修改 Contract 或停止。

要求模型「反思一下」可以提供額外訊號，但 Reflection 仍是模型輸出。它不能取代外部 State、Budget、Scope Gate 與 Completion Evidence。

用「跑測試並修正失敗」走一次

假設使用者要求 Coding Agent：

跑完 checkout service 的測試，修正目前失敗，但不要修改 payment provider integration。

一個受控 Loop 可以這樣推進：

建立 Turn，載入 Task Contract、Allowed Scope 與 Budget。
Context Builder 提供 Checkout Service 規範與本輪可見 Capabilities。
模型提出執行指定 Test Suite 的 Tool Request。
Harness Canonicalize Command 與 Workspace，完成 Policy Check 後執行。
Command Result 回報兩個 Test Failure，完整 Log 另存為 Artifact。
模型讀取相關檔案，提出 Patch。
Write Operation 通過 Scope Check，執行後留下 Diff 與 Operation Receipt。
模型要求再次執行測試。
Unit Tests 通過，但 Completion Gate 發現 Payment Integration Contract Test 尚未執行。
Terminal Candidate 被拒絕，Loop 回到必要驗證步驟。
Contract Test 通過，Scope Check 確認沒有修改 Provider Integration。
Run 提交 completed State，交付 Diff、Test Evidence 與 Terminal Reason。

若模型在第 9 步直接寫「已修好」，那只是自然語言結論。完成與否取決於 Task Contract、Policy 與 Evidence，不取決於語氣有多肯定。

最小可靠 Agent Loop 的邊界

一個 Agent Loop 至少要具備：

Typed Input、Output 與 Control Items
明確的 Action Authority
Canonical Operation 與 Tool Version
Tool Request／Terminal Result Correlation
Explicit State Transition
Budget、Cancellation 與 Waiting Semantics
Terminal Candidate Evaluation
可重建的 Event History

Agent Loop 不會單獨解決整套 Harness：

Context Selection、Compaction 與 Memory 治理留到 Part 04。
Tool Schema、Skill、Hook、Plugin 與 MCP 留到 Part 05。
Thread Persistence、Checkpoint 與 Runtime Lifecycle 留到 Part 06。
Multi-agent Delegation 與長任務 Handoff 留到 Part 07。
Retry、Unknown Outcome 與 Side-effect Recovery 留到 Part 08。
Permission、Sandbox 與 Trust Boundary 留到 Part 09。
Completion Contract、Verifier 與 Evaluation 留到 Part 10。
Trace、Replay、Metrics 與 SLO 留到 Part 11。

Agent Loop 是控制引擎，不是整台車。

用十個問題審查一段 Agent Loop

Controller 解析實際 Typed Items，還是只看 Provider Stop Signal？
Tool、Arguments 與 Resource 是否先解析成 Canonical Operation，再授權？
每個 Tool Request 是否都有唯一 Terminal Result？
Progress Event、Background Completion 與 Tool Result 是否有不同 ID 與語意？
多 Tool Request 的 Sequential／Parallel Policy 是否明確？
Transcript 與 Canonical Runtime State 是否分離？
Assistant Message 是直接完成，還是 Terminal Candidate？
Completed、Waiting、Failed、Cancelled 與 Budget Exhausted 是否分開？
Approval、Cancel、Reconnect 與 Event Replay 是否有雙向 Protocol？
每個 Transition 能否從 Event History 重建？

若實作只有：

while response.has_tool_call:
 response = call_model(run_tool(response.tool_call))

它可以當 Demo 起點。距離可恢復、可稽核、可治理的 Agent Loop，還有不少箭頭要補。

理論轉實作：Part 03 檢查表

Part 04 會接著處理 Agent Loop 每次 Inference 前最難的一個輸入問題：在有限 Context Window 裡，哪些資料應該進來、哪些應留在 Durable State、哪些要靠 RAG 取得，以及 Memory 為什麼不能只是無限累積的聊天摘要。

References

OpenAI, Unrolling the Codex agent loop, 23 January 2026. ↩
Anthropic, How tool use works, accessed 8 July 2026. ↩
Anthropic, Building effective agents, 19 December 2024. ↩
OpenAI, Unlocking the Codex harness: how we built the App Server, 4 February 2026. ↩ ↩²