2026 年 7 月 25 日，一篇談 AI Agent 三層架構——Agent Harness、Loop Engineering 與 Graph Engineering——的 X 長文，把三個常被混在一起的詞放到同一張圖上。這個分類很有用，但如果你把它誤讀成固定堆疊的「三層蛋糕」，反而容易在錯的地方修問題：工具壞了去改流程圖、沒有驗收標準卻一直換模型，或只為了看起來專業就拉出十幾個 Agent。
這篇 AI Agent 三層架構教學專為沒有技術背景的讀者寫。我們不把流行詞再翻譯一次，而是用一個「電商退貨 Agent」完整走過 Harness、Loop、Graph，最後給你一張故障診斷表與一份可以直接貼進專案的任務契約。讀完後，你會知道該加工具、加驗收循環，還是把穩定流程畫成 graph。
先說結論：AI Agent 三層架構是在回答三個不同問題
🤖 記憶口訣：診斷 Agent 系統時，可以分別檢查 Harness（能力與邊界）、Loop（行動與驗證）、Graph（路徑與狀態）。
再白話一點：Harness 管「工作條件」；Loop 管「反覆做到合格」；Graph 管「下一步由誰做、狀態怎麼交接」。
- Harness：Agent 能讀什麼、能呼叫哪些工具、記憶放哪裡、權限到哪裡，以及發生什麼事時如何留下紀錄。
- Loop：Agent 做完一輪後看什麼證據、收到什麼回饋、什麼情況再試，以及何時成功、暫停或轉人工。
- Graph：有哪些工作節點、誰先誰後、哪些能平行、何時分支與合流，以及哪個動作前要插入人工核准。
先把最重要的誠實話放在前面：本文把「三層」當成教學鏡頭，不把它宣稱為跨廠商共同標準。截至 2026 年 8 月 1 日，LangChain 採用很廣的 Harness 定義；Anthropic 在 Agent 評測脈絡中，會分別描述 model＋agent harness，以及 Agent 作用的 tools／environment；Microsoft Agent Framework 則把 Agents、Harness、graph-based Workflows 列成不同能力類別。邊界會因框架而移動，但三個問題仍然很好用。
第一個視角 Harness：先替 AI 準備一個能工作、也有邊界的環境
想像你請來一位很聰明的廚師，卻只給他一張椅子。沒有廚房、食材、冰箱、訂單、門禁與清潔紀錄，他再會想也端不出一道可交付的菜。模型原生可以產生文字；要讓它持久保存進度、查即時資料、執行程式、操作外部系統並接受權限約束，還需要模型外面的工作系統。這就是 Harness 最好懂的角色。
Anthropic 的 Agent 評測文章把 agent harness（或 scaffold）描述為讓模型能以 Agent 身分行動的系統：處理輸入、編排工具呼叫並回傳結果。LangChain 的文章則把 system prompt、skills、MCP、檔案系統、sandbox、handoff 與 middleware 列為 Harness 可能包含的元件。你不必爭哪個邊界才「正統」，實作時把責任寫清楚比較重要。
一個實用 Harness 通常要回答 6 件事
- Context（工作說明）：任務、政策、使用者需求與當前狀態怎麼送進模型。
- Tools（手腳）：搜尋、讀檔、資料庫與 API 各自接受什麼輸入、回傳什麼結果。
- State（交接簿）：對話、進度、checkpoint 與產物如何跨回合保存。
- Permissions（門禁）：哪些工具唯讀、哪些寫入前要核准、憑證能碰到哪些資源。
- Execution（執行規則）：timeout、retry、模型路由、並行數量與成本上限放在哪裡。
- Observability（行車紀錄器）：模型回合、工具輸入輸出、失敗位置、延遲與花費如何追蹤。
Anthropic 在長時間寫程式的實驗裡，曾用 initializer、feature list、claude-progress.txt 與 git history 幫下一個 context 接手。重點不是每個 Agent 都照抄這四樣，而是看出問題本質：「記得工作做到哪裡」是系統設計，不是再補一句「請記住」。若你想先把這層打牢，可接著讀〈AI Agent Harness 是什麼？〉與〈動手搭一個最小 Harness〉。
第二個視角 Loop：讓 AI 不是一直做，而是用新證據修正到合格
Harness 給了 Agent 手腳，Loop 決定它如何重複使用這些手腳。OpenAI Agents SDK 的 Runner 文件描述了一個基本 agent loop：呼叫模型、檢查輸出；若有 tool call 就執行後把結果送回去，若有 handoff 就換 Agent 繼續，直到得到終點輸出，或碰到 turn 上限等中止狀態。
但 Loop Engineering 不只是在外面寫一個 while true。LangChain 在 2026 年 6 月的多層 Loop 整理中，把基本 agent loop 外面再包 verification loop、event-driven loop 與改良 harness 的回饋循環。最值得新手先學的不是「永遠運轉」，而是有限重試＋外部證據＋清楚出口。
好的 Loop 有 4 個煞車零件
- 成功證據：測試通過、schema 合法、連結可開、系統紀錄真的出現，而不是 Agent 自己說完成。
- 資源上限：明寫最大回合、重試次數、截止時間或可接受成本。
- 失敗分類：短暫 API 錯誤才重試；政策不符、資料不足或高風險動作走另一條路。
- 逃生出口：轉人工、等待 webhook、延後排程，或帶著失敗原因結束。
白話說，Loop 像改作文：不是重寫十次就會變好，而是每一輪都拿到「哪一項沒及格」的新批改，再針對那一項修正。若驗收單沒有變、錯誤訊息也沒有變，繼續燒 token 通常只是把同一次錯誤演得更久。想深挖觸發器、記憶與停止條件，可看〈Loop Engineering 循環工程完整教學〉。
第三個視角 Graph：把順序、分支、平行與人工關卡寫成路線圖
當工作不再只有「做 → 檢查 → 再做」，你會遇到另一種問題：客服案件要先驗證身分還是先查訂單？兩個查詢能不能同時跑？退款前誰核准？失敗後回上一格還是轉人工？Graph Engineering 在本文指的，就是把這些 control flow（控制流程）明確建模。
LangGraph 官方 Graph API用三個核心物件解釋：State 是目前共用工作表，Node 是做事的函式，Edge 決定接著跑哪個 Node。Node 可以封裝 Agent 或一般函式，也可在節點中插入人工核准；Graph 則能組合固定與條件式 edge、平行 fan-out／fan-in，或回到前面 Node 的受控循環。因此，Graph 與 Loop 不是新舊替代關係，graph 本身就能承載 loops。
另外，Graph 也不等於把流程畫漂亮。持久化要設定 checkpointer（使用託管服務時可能由平台代管）；平行分支同時更新一個 state key 時要定義 reducer；中斷後重跑寫入動作時，寫入端還要真正支援 idempotency key、upsert 或 read-before-write。如果你只是讓一個 Agent 使用三個工具完成一件開放任務，先保持簡單；等 trace 顯示穩定分支、相依關係或高風險關卡，再把它們固化成圖。
完整走一次：一個退貨 Agent 如何同時用 Harness、Loop 與 Graph
假設顧客輸入：「包裹遺失，請處理訂單 ORD-42。」以下政策、訂單編號與限制全是教學情境；我們只用它追蹤三個工程視角，不對真實商家的退款規則作假設。
Step 1：Harness 先把能力與邊界準備好
Agent 只拿到三個唯讀工具：get_order()、get_shipping_event()、get_refund_status()；真正寫入的 issue_refund() 使用另一組受限憑證，並在高影響動作前暫停核准。Case state 存在 checkpoint，工具參數採結構化 schema，每個寫入帶 idempotency_key，trace 記錄節點、工具、狀態與結束原因。
Step 2：Loop 用「系統紀錄」判斷完成
內層 agent loop 負責補齊訂單與物流事實；外層 verification loop 在核准執行後重新查退款系統。停止條件不是回覆裡出現「已退款」，而是系統紀錄同時對上案件、訂單、核准內容與 transaction id。若外部服務仍在處理，就存下狀態、等待事件再醒來；若碰到已分類的永久錯誤，就帶著證據轉人工。
Step 3：Graph 決定每種證據可以走哪條路
流程先驗證請求，再查訂單與物流；兩個查詢沒有相依時可以平行。合流後由固定規則判斷：不符合就說明原因；資料有歧義就轉人工；符合且需要核准就停在 approval node；核准後才執行退款，最後進入驗證 Loop。這裡讓模型處理模糊語言，讓程式掌管政策、權限、金額與完成證據。
把它縮成框架無關的偽代碼，大致長這樣：
MAX_MODEL_TURNS = 6 # 本文示意值
MAX_VERIFY_RETRIES = 2 # 本文示意值
state = checkpoints.load_or_create(case_id, verify_retries=0)
while state.node not in TERMINAL_NODES:
enforce_budget_and_deadline(state)
if state.node == "gather":
state.plan = agent_loop(
tools=[get_order, get_shipping_event],
max_turns=MAX_MODEL_TURNS,
)
state.node = "policy"
elif state.node == "policy":
state.decision = evaluate_policy(state.plan)
state.node = route_from_policy(state.decision)
elif state.node == "approval":
state.approved = pause_for_human(
plan=state.plan,
decision=state.decision,
)
state.node = "execute" if state.approved else "rejected"
elif state.node == "execute":
state.refund = issue_refund(
order_id=state.plan.order_id,
amount=state.decision.approved_amount,
idempotency_key="refund:" + case_id,
)
state.node = "verify"
elif state.node == "verify":
proof = get_refund_status(state.refund.id)
if matches_approved_refund(
proof,
order_id=state.plan.order_id,
amount=state.decision.approved_amount,
):
state.node = "success"
elif proof.is_transient and state.verify_retries < MAX_VERIFY_RETRIES:
state.verify_retries += 1
checkpoints.save(state)
schedule_retry(case_id)
return "WAITING"
else:
state.node = "escalate"
checkpoints.save(state)6 個模型回合與 2 次驗證重試，是這個例子主動設定的上限，不是任何 SDK 的預設值。為了看清架構，偽代碼也省略了型別、認證、交易處理、錯誤分類與 durable queue；一旦接上真實寫入工具，這些都要由 Harness 與 Graph 明確承擔。
AI Agent 三層架構怎麼選？先用故障症狀定位
- 拿不到正確資料、忘記進度、工具參數亂掉、權限太大：先查 Harness。縮窄工具、補 schema、持久化 state、拆開讀寫憑證。
- 做得動卻提早宣布完成、同一錯誤一直重試、成本失控：先查 Loop。補外部 postcondition、新的失敗回饋、明確上限與 escalation。
- 步驟順序錯、平行工作互相覆蓋、核准點被繞過：先查 Graph。把 node、edge、共享 state、join 與人工 gate 寫清楚。
- 三種症狀一起出現：組合修正，但一次只改一個可測量變因，再用 eval 比較前後版本。
還有第四種可能：工具、驗證與流程都清楚，模型仍反覆誤解同一種輸入。這時才把 prompt、模型能力或訓練／評測資料列為主要假設。可靠性是整個系統的結果；不要把所有錯都怪模型，也不要反過來宣稱模型完全不重要。
從零實作：照這 5 步，不要先畫一張巨型 Graph
① 先寫完成契約
先問「什麼外部事實出現，才叫完成？」把下面這段複製到專案，換成自己的答案：
goal: 用一句可驗證的結果描述任務
evidence:
- 必須通過的測試或系統狀態
allowed_tools:
- read_only_tool
max_attempts: 3
human_gate:
- 任何不可逆或高影響動作
on_failure: 保存證據並轉人工② 用最小 Harness 跑一條真實任務
一開始只給兩三個必要工具、單一 state 與一個 trace。先觀察 Agent 真正怎麼做，再決定哪些能力、權限與記憶是必要的。不必要或彼此重疊的工具，會增加模型的選擇與 context 負擔；權限越廣，錯誤的影響範圍也越大。
③ 只加一個 Verification Loop
挑最昂貴的失敗，替它加一個能反證的 grader。能用測試、schema 或 system of record 就先用；主觀品質才交給獨立 reviewer，再把最大重試與轉人工條件寫死。
④ Trace 顯示穩定路徑後，再 Graph 化
把重複出現的分支、平行工作、等待與核准點抽成 nodes 和 edges。若下一步仍需要模型臨場規劃，就保留在 Agent node 裡；若順序、權限或復原路徑必須由開發者控制，就放進 graph。
⑤ 用任務結果驗收，不用架構名詞驗收
至少追蹤 task success、危險寫入、重複副作用、人工介入率、工具錯誤、回合數、延遲與每件成功任務成本。想建立完整 trace，可搭配〈Agent Observability 是什麼？〉；牽涉 API Key 與敏感工具時，再讀〈AI Agent 密鑰安全教學〉。
想親手試：Loop 與 Graph 各選一條入門路
截至 2026 年 8 月 1 日，想觀察現成 agent loop，可依 OpenAI Agents SDK Quickstart 執行 pip install openai-agents；想親手定義 State、Nodes 與 Edges，可依 LangGraph Quickstart 執行 pip install -U langgraph。這是兩條各自獨立的入門路，不必同時安裝。
如果你在舊教學裡看到 AutoGen GraphFlow，要注意目前的官方定位：Microsoft 的 AutoGen repository 已標示 maintenance mode，並建議新使用者從 Microsoft Agent Framework 開始；GraphFlow 文件仍標示 experimental。這不抹去它的歷史價值，但新專案的第一站應改看現行 Agent Framework 與 Workflows 文件。
5 個常見錯法：架構越大，不代表 Agent 越可靠
- 還沒看 trace 就先畫 30 個 nodes：你固化的可能只是對工作的猜測。先跑小系統，再 formalize 穩定路徑。
- 讓執行者只靠同一份脈絡自評：先用 deterministic check；需要判斷時，再隔離 reviewer context 或插入人類。
- 把「繼續努力」當 Loop：沒有新證據、重試上限與 escape hatch 的循環，只會增加成本。
- 以為 checkpoint 等於不會重複寫入：恢復時某個 node 可能重新開始；付款、寄信、刪除等 side effect 要用 idempotency key 或 read-before-write。
- 把所有東西都塞進 Harness：太多工具、噪音 context 與寬鬆權限，會同時增加選錯工具與擴大事故範圍。
常見問題 FAQ
1. AI Agent 三層架構是業界公認標準嗎？
不該這樣宣稱。截至 2026 年 8 月 1 日，LangChain、Anthropic 與 Microsoft 對 Harness、tools、environment、runtime、workflow 的邊界畫法不同。本文只把三者當成好用的診斷視角。
2. 每個 Agent 都要同時做 Harness、Loop、Graph 嗎？
不必一開始全部做。單次問答可能只需要模型與簡單工具；開放式任務先用最小 Harness＋agent loop；真的出現穩定分支、平行與核准需求，再加入 graph。
3. Harness 就是 Agent Framework 嗎？
不完全相同。以 LangChain 現行文件的分類來說，framework 提供開發抽象，runtime 承接應用執行與 context，persistence 則另外透過 checkpointer 等機制完成；harness 是讓模型實際工作的配置與機制。某個 framework 可以提供現成 harness，也可能只提供底層元件；不同廠商也可能合併這些責任。
4. Loop Engineering 就是寫一個無限迴圈嗎？
不是本文要教的做法。可運作的 Loop 需要成功證據、失敗回饋、資源上限與明確出口；無限重試只有「重複」，沒有工程化驗收。
5. Graph Engineering 等於多 Agent 嗎？
不是。LangGraph 官方文件明確說 Node 可以包含 LLM，也可以只是普通程式。單一 Agent 加上幾個固定檢查，以及透過 interrupt 插入的人工核准，同樣能形成 graph。
6. Graph 一定是不能回頭的 DAG 嗎？
不一定。LangGraph 支援 conditional edge 回到先前節點，也提供 execution step 上限。重點是 cycle 的入口、證據與出口可被控制，而不是把所有箭頭都禁止回頭。
7. 多加一個 reviewer，就會更可靠嗎？
不一定。LLM reviewer 也會有盲點；Anthropic 的長任務實驗先用 few-shot 範例校準 evaluator，其評測指南也要求 LLM grader 持續與人類判斷對照。能用測試、schema、資料庫狀態驗證的地方先用確定性檢查，主觀判斷再加入獨立 reviewer 與人類。
8. 新手第一個該做什麼？
先寫完成契約。把 goal、evidence、allowed tools、max attempts、human gate、on failure 六欄填完，再用一條真實小任務測試。這比先選最熱門框架更能暴露缺口。
給新手的 5 個重點
- Harness 解決能力、狀態、權限與觀測問題。
- Loop 解決證據、回饋、有限重試與停止問題。
- Graph 解決順序、分支、平行、合流與人工關卡問題。
- 三者會重疊；LangChain、Anthropic 與 Microsoft 的現行文件採用不同邊界與組合。
- 先用最小系統取得 trace，再把最昂貴的失敗工程化。
📚 延伸閱讀
- 〈AI Agent Harness 是什麼？〉：把工具、記憶、權限與執行層再拆深一層。
- 〈Loop Engineering 循環工程〉：看 trigger、驗收、記憶與煞車如何組成長任務。
- 〈Graph Engineering 實作教學〉：把 nodes、edges、anchors 與動態工作流做成可操作流程。
- 〈Orca Graph Engineering〉：用多 Agent 工作圖練習 fan-out、驗證與合流。
- 〈LangGraph 為何要做可復原流程圖？〉：補齊 state、checkpoint 與 durable execution 的原理。
- AlphaLab AI 專區：從模型、工具到 Agent 系統，建立完整學習地圖。
結語：今天先替你的 Agent 寫一張驗收單
回到那句最好記的話：Harness 是工作條件，Loop 是反覆做到合格，Graph 是下一步往哪走。真正成熟的做法不是一次把三層堆滿，而是看著一個具體失敗，替它補上最小、可驗證的工程槓桿。
現在就打開你正在做的 Agent 專案，先寫下 goal、evidence、max_attempts 與 human_gate。如果你想把這套方法變成可重複的 AI 工作流，再到 AlphaLab 課程，沿著真實案例一步步把「會回答」升級成「能驗收、能復原、能負責任地執行」。