---
site: "zyx.tw"
title: "Agent Loop 讓模型提出請求，由程式執行並送回結果"
description: "理解模型與程式的分工，才能分清停止與完成。"
url: "https://www.zyx.tw/map/harness/agent-loop"
---

# Agent Loop 讓模型提出請求，由程式執行並送回結果

紀錄 044，觀念 L1，619 字，2 分鐘，v2.0.0，更新 2026-11-16

harness 是模型外圍的程式。模型讀進內容、輸出內容，不能直接讀檔或下指令。

工具呼叫就是模型提出的請求，指定工具與參數。Agent Loop 由 harness 問模型、執行工具，再把結果加入對話，交給模型決定下一步。

## 誰做什麼

模型沒有狀態，對話存在 harness 的 messages。同一段 messages 可以交給另一個模型接著做。

下圖呈現模型、harness 與工具的分工。

```text
╭───────────╮  messages + tools   ╭───────────╮
│           │ ──────────────────> │           │
│  HARNESS  │                     │   MODEL   │
│           │ <────────────────── │           │
╰──┬─────┬──╯  text or tool call  ╰───────────╯
   │     ^
   │ run │ tool result
   v     │
╭──┴─────┴──╮
│   TOOLS   │  read  edit  bash
╰───────────╯
```

Figure: A harness sends messages and tool definitions to a model. The model answers with text or a tool request. The harness runs the tool and sends the result back.

1. Request: harness 把對話與工具定義送給模型。
2. Reply: 模型回覆文字，或提出工具請求。
3. Run: harness 執行工具。模型沒有碰到電腦。
4. Result: 工具結果加進對話，回到第 1 步。

## 讀檔請求如何變成答案

下圖從使用者問「README 的第一行寫什麼？」開始。模型提出 read\_file 請求，參數指向 README.md。

harness 執行讀檔，把結果加進對話，再將整段對話送給模型。模型回答第一行是 # Hello，不再要求工具，迴圈結束。

請求的格式見 工具呼叫的格式。

1. USER: 使用者的要求是對話的第 1 則訊息。

```text
README 的第一行寫什麼？
```

2. MODEL: 模型不直接回答，先提出工具請求。

```text
tool call: read_file
{"path": "README.md"}
```

3. HARNESS: harness 執行工具。模型沒有碰到檔案。

```text
read_file("README.md")
```

4. TOOL: 結果加進對話，整段對話再送給模型一次。

```text
tool result
# Hello
A small demo.
```

5. MODEL: 模型不再要求工具，迴圈結束。

```text
README 的第一行是「# Hello」。
```

Figure: One run of the agent loop: the user asks, the model requests a tool, the harness runs it, the result goes back, and the model answers.

## 沒有工具請求，就停止迴圈

各家 API 用不同欄位表示停止原因，例如 Anthropic 的 stop\_reason。下圖的簡化程式以 reply.tool\_calls 是否為空，判斷是否結束。

工具失敗時，也要把錯誤訊息當成結果送回。模型讀到錯誤，才能換做法。

```text
messages = [user(task)]
for turn in range(MAX_TURNS):
    reply = model(system, tools, messages)
    messages.append(reply)
    if not reply.tool_calls:
        return reply.text
    results = []
    for call in reply.tool_calls:
        results.append(run_tool(call))
    messages.append(user(results))
raise TooManyTurns
```

Figure: Pseudo code of an agent loop: ask the model, stop when it requests no tool, otherwise run each tool and append the results.

1. Ask: 每一輪都送出完整的 messages。模型沒有記憶，只讀這次送來的內容。
2. Stop: 模型沒有要求工具，迴圈結束。
3. Run: harness 逐一執行模型要求的工具。
4. Feed: 工具結果以 user 訊息送回。下一輪模型就讀得到。
5. Limit: 輪數上限避免迴圈停不下來。

## workflow 與 agent 的差別

Anthropic 把固定步驟的流程稱為 workflow。agent 則由模型依工具結果決定下一步。

## 驗證也在迴圈裡

context 是一次請求送給模型的全部內容。Claude Code 的文件把工作分成收集 context、採取行動、驗證結果，三個階段共用同一個迴圈。

停止只代表模型認為做完了，任務是否完成仍要靠驗證判斷，見 怎樣才算完成。

## 來源

- [Building effective AI agents](https://www.anthropic.com/engineering/building-effective-agents), Anthropic
- [How tool use works](https://platform.claude.com/docs/en/agents-and-tools/tool-use/how-tool-use-works), Claude API docs
- [How Claude Code works](https://code.claude.com/docs/en/how-claude-code-works), Claude Code docs
- [How to Build an Agent](https://ampcode.com/how-to-build-an-agent), Thorsten Ball
- [12-factor agents](https://github.com/humanlayer/12-factor-agents), Dex Horthy

## 地圖

- 先讀：[把完整任務交給 Claude Code，以實際操作結果判斷完成](https://www.zyx.tw/map/basics/what-claude-code-is.md)
- 原理：[Skill 的載入由模型決定，harness 負責把全文送進對話](https://www.zyx.tw/map/basics/how-a-skill-loads.md)
- 原理：[工具以名稱、說明與參數格式約定請求，再用同一個 id 對回結果](https://www.zyx.tw/map/harness/tool-calls.md)
- 原理：[每輪重送 context，固定前段與對話長度要分開管理](https://www.zyx.tw/map/harness/context-is-resent.md)
- 相關：[LLM 每次只預測下一個 token，長回覆靠反覆生成](https://www.zyx.tw/map/harness/llm-basics.md)
- 回到：[Harness](https://www.zyx.tw/map.md)
