zophos

← Notes · 04-agent loop:跑到模型不再要工具為止.md

agent loop:跑到模型不再要工具為止

迴圈的形狀很小,難的是把模型搞砸的每一步都當成輸入餵回去

把工具、模型這兩端接起來、讓它們一輪一輪跑下去的,就是 agent loop。它的核心(harness)不碰終端機、不碰 session 檔、不知道自己被誰驅動——每次被呼叫只跑一步;把它一步步轉起來的,是外面那層前端。


迴圈的形狀

核心的回合函式一次只做一步:太長就先壓縮,否則來回 provider 一趟。

// run_turn:一步
if 過線了 { 壓縮; return Ok(TurnOutcome::Compacted { .. }); }   // 另一個題目
if *rounds >= MAX_TURNS { bail!("gave up after {MAX_TURNS} turns") }
*rounds += 1;
self.run_one_exchange(messages, on_event, token).await          // 完成 / 取消 / 跑完一輪工具

迴圈本身在外殼:

// 前端:一句 prompt 的整個回合
let mut rounds = 0;
let outcome = loop {
    match harness.run_turn(&mut messages, on_event, &token, &mut rounds).await? {
        TurnOutcome::ToolRound => log.append_new_messages(&messages)?,  // 這輪先存檔,再進去
        TurnOutcome::Compacted { .. } => /* 把壓縮寫進 log */,
        done => break done,                                             // 完成或取消
    }
};

一趟 run_one_exchange 做的事:送出 messages + 可用工具 → 串流模型的回覆 → 它有沒有要工具?

if tool_calls.is_empty() {
    // 沒有要工具 = 這就是最終答案
    messages.push(Message { role: Role::Assistant, content: /* 思考 + 文字 */ });
    return Ok(TurnOutcome::Completed);
}
// 有要工具:跑完、把結果接回 messages,回報「跑完一輪工具」

整個 agent 就這麼一句:送訊息 → 模型要不要工具 → 不要就結束,要就跑完餵回去再問。 停止條件沒有別的——模型不再要工具,迴圈就停。

迴圈原本整個在核心裡(for _ in 0..max_turns,跑到模型不再要工具才回來)。後來搬到外殼,原因是存檔:核心不碰磁碟,所以它跑完幾十輪工具才回來的話,回合中途關掉終端機,這句 prompt 和所有已經做完的工具呼叫都不在紀錄裡——檔案早就被改了,接回 session 的模型卻不知道。現在核心每跑完一輪工具就把控制權交回來,外殼先存檔再進去,最多只丟正在跑的那一輪(見紀錄只 append)。迴圈的形狀沒變,只是換了誰來轉。


工具是模型的詞彙表

模型能呼叫什麼,來自每個工具自己報的三件事(Tool trait 的 name / description / schema)。harness 把它們收集成 ToolSpec 送給 provider:

let tool_specs: Vec<ToolSpec> = self.tools.iter().map(|t| ToolSpec {
    name: t.name().to_string(),
    description: t.description().to_string(),
    parameters: t.schema(),          // 工具自己描述它的參數
}).collect();

模型回一個 tool call 時,按名字找回同一個物件來執行:

let tool = self.tools.iter().find(|t| t.name() == name);   // 線性掃一個 Vec<Box<dyn Tool>>

所以一個工具是單一事實源:「告訴模型它能做什麼」(name/description/schema)和「實際做的事」(call)來自同一個 trait 物件,不會各寫一份、對不上。派發用線性掃描而不是 HashMap——四個內建工具加上幾個 MCP 工具,掃描比「維護一張要跟 Vec 同步的表」省事。


模型的錯誤是輸入,不是例外

模型呼叫一個不存在的工具、傳錯參數、或命令本身失敗——這些不是迴圈該崩掉的錯誤,是模型該看到的結果:

let (output, is_error) = match self.tools.iter().find(|t| t.name() == name) {
    Some(tool) => match tool.call(args, token, &mut on_output).await {
        Ok(output) => (output, false),
        Err(err)   => (format!("{err:#}"), true),    // 工具失敗 → 當成結果
    },
    None => (format!("no such tool: {name}"), true), // 工具不存在 → 當成結果
};

兩種都變成一個 is_error 的 ToolResult,照常接回 history。模型下一輪就看到 no such tool: xxx 或 {err:#},自己換個做法。只有 provider 那端真的出錯(連不上、回覆串到一半斷掉)才回 Err、中斷這個回合。

釐清職責界線:Zophos 不處理模型失敗的呼叫,如實回傳讓模型自己調整。


history 永遠要是一個完整的交換

provider 的規矩是:一個 tool call 一定要配一個 tool result,否則下一次請求就是不合法的。所以就算回合在中途被取消,也要把整批補成完整的交換:

for (id, name, args, signature) in tool_calls {
    let (output, is_error) = if token.is_cancelled() {
        ("cancelled - turn was interrupted before this tool ran".into(), true)  // 沒輪到的也補一個結果
    } else {
        /* 跑這個工具 */
    };
    call_blocks.push(/* tool call */);
    result_blocks.push(/* tool result */);
}
messages.push(Message { role: Role::Assistant, content: call_blocks });  // 呼叫
messages.push(Message { role: Role::User,      content: result_blocks }); // 結果
if token.is_cancelled() {                // 取消檢查放在「整批已進 history」之後
    return Ok(TurnOutcome::Cancelled { partial_reply: None });           // 取消是一個值,見 14
}

取消的檢查放在整批結果都進了 messages 之後。一個真的跑了、真的寫了檔案的工具,它的結果不會因為同批後面某個呼叫還沒輪到就被丟掉——history 永遠是一個完整、合法的交換。真實紀錄OS過程。


一道便宜的保險

MAX_TURNS——一句 prompt 最多來回 provider 幾次。不是什麼 loop-detection 的聰明啟發式,就是一個平上限:每一趟都是一次付費 API 呼叫,一個永遠不收斂的 provider/工具組合會一直燒錢。便宜的保險,擋住最壞情況。

上限一開始是 10,後來調到 50:一般寫程式的任務——讀檔、改、跑測試、再修、再測——很容易超過 10 趟。迴圈搬到外殼之後,計數器也由外殼持有、每次重新進入都帶著同一個(那個 &mut rounds),存檔或壓縮後重新進入,不會把額度重置。

曾經還有第二道 max_tool_calls(所有工具執行的總數)。想法是:一個回合可以 fan out 成好幾個 tool call,所以「工具執行數」可能遠超「往返次數」,得分開限。但從第一性原理一問就垮了——fan-out 多出來的真實成本是 token,而 token 已經被壓縮(見壓縮)bound 住了,不是呼叫次數。工具執行數這道防線要擋的,往返上限加上壓縮早就擋了。多餘,砍掉,只留一道。

(而且它本身也不是「runtime 要幾個就跑幾個工具」的保證——模型一次要多個工具,和 runtime 怎麼執行,是兩件獨立的事。)


總結

  1. 迴圈的形狀是一句話。 送訊息 → 模型要不要工具 → 不要就結束,要就跑完餵回去再問。停止條件就是「模型不再要工具」。核心一次只跑一步,迴圈由外殼轉,每輪之間外殼先存檔。

  2. 工具是模型的詞彙表,而且是單一事實源。 name/description/schema 告訴模型能做什麼,call 是實際做的,同一個 trait 物件——告知和執行不會對不上。

  3. 模型的錯誤是輸入,不是例外。 工具不存在、參數錯、命令失敗、甚至取消,全部當成結果餵回去讓模型自己修;只有 provider 那端真的出錯才中斷。這是 agent 能自我修正的根本。

  4. history 永遠要是完整的交換。 每個 tool call 配一個 result,所以結果先整批進 history、取消檢查放在那之後——已經執行的工具,副作用和紀錄不會不一致。