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 怎麼執行,是兩件獨立的事。)
總結
-
迴圈的形狀是一句話。 送訊息 → 模型要不要工具 → 不要就結束,要就跑完餵回去再問。停止條件就是「模型不再要工具」。核心一次只跑一步,迴圈由外殼轉,每輪之間外殼先存檔。
-
工具是模型的詞彙表,而且是單一事實源。
name/description/schema告訴模型能做什麼,call是實際做的,同一個 trait 物件——告知和執行不會對不上。 -
模型的錯誤是輸入,不是例外。 工具不存在、參數錯、命令失敗、甚至取消,全部當成結果餵回去讓模型自己修;只有 provider 那端真的出錯才中斷。這是 agent 能自我修正的根本。
-
history 永遠要是完整的交換。 每個 tool call 配一個 result,所以結果先整批進 history、取消檢查放在那之後——已經執行的工具,副作用和紀錄不會不一致。