一個動作一張 JSON,工具名稱加參數,框架解析完去執行,結果再當字串還給模型。smolagents 的 ToolCallingAgent 系統提示裡示範的動作長這樣:

1
{ "name": "image_transformer", "arguments": {"image": "image_1.jpg"} }

這段我讀的是 v1.26.0 的 toolcalling_agent.yaml 原檔文字。官方 guided tour 說 ToolCallingAgent 寫的就是這種格式,原句是 This is the common format used in many frameworks (OpenAI API)。intro_agents 那頁也提到,Anthropic、OpenAI 等多家用的格式都是「工具名稱加參數的 JSON」的各種變體。

下面我把它叫做舊做法,純粹是對照用的說法。官方沒有寫過 smolagents 先用 JSON、後來改成 code,我在文件和 v1.26.0 的原始碼樹裡也找不到這種痕跡,兩種 agent 在同一個版本並存。能對上的時間點只有兩個:CodeAct 論文的 arXiv v1 是 2024 年 2 月 1 日,smolagents 的 v0.1.0 是 2024 年 12 月 27 日。至於為什麼主打 CodeAgent,後面只引官方原句,不替它歸納。

同一個任務,寫兩遍

任務是我設想的,不是跑出來的:查廣州和上海的人口。城市名取自官方 CodeAgent 提示裡的範例。

JSON 這邊,每個查詢是一個動作:

1
{ "name": "web_search", "arguments": {"query": "Guangzhou population"} }
1
{ "name": "web_search", "arguments": {"query": "Shanghai population"} }

CodeAgent 這邊,同一件事是一段程式:

1
2
for city in ["Guangzhou", "Shanghai"]:
print(f"Population {city}:", web_search(f"{city} population"))

官方範例的 print(...) 那行,building_good_agents 頁貼的版本少一個右括號,v1.26.0 的 code_agent.yaml 原檔那行是完整的;上面這段照完整版寫,仍然只是示意,不是原文。論文 Fig. 1 對這個落差的說法是 text or JSON have to take action for every input。我讀到的 ToolCallingAgent 範例都是一次一個 action blob,至於它在各版是否支援一輪多個呼叫,我沒查。

用日常的東西比:JSON 像遙控器,只能按上面已經有的鈕,一次按一顆;code 像能錄巨集,把「每個頻道各看十秒」錄成一個動作。遙控器的好處是你不會按到不存在的鈕,巨集的好處是不必有人預先替每一種組合做一顆鈕。官方的說法是這兩邊各有取捨:

面向 ToolCallingAgent(JSON) CodeAgent(Python)
動作長相 name 加 arguments 的 JSON blob Python 程式碼片段
上一步的結果怎麼到下一步 observation 一律是字串;提示規定 Never use variable names as the action arguments, use the value instead 提示寫明 The state persists between code executions,變數和 import 都留著
官方列的強項 Reliable、Safe、Interoperable Highly expressive、Flexible
官方列的代價 Low expressivity、Inflexible Risk of errors、Less predictable、Requires secure execution environment
官方建議的情境 simple, atomic tools;high reliability;像 dispatcher 或 controller reasoning、chaining、dynamic composition;像 problem solver 或 programmer

表裡每一格都是官方文件或系統提示的內容,第二列的「observation 一律是字串」與「變數留著」並排,是我自己把兩份提示放在一起看才看出的差異。

官方給 CodeAgent 的理由有四條,intro_agents 與 secure_code_execution 兩頁都列:composability(could you nest JSON actions within each other)、object management(how do you store the output of an action like generate_image in JSON?)、generality、representation in LLM training data。語氣很重,secure_code_execution 頁寫了一句 If JSON snippets were a better way, this package would have been written in JSON snippets and the devil would be laughing at us.

這四條是論述,文件本身沒有附 smolagents 自己的 benchmark 數字。要看數字得去它引的論文。

論文那張表,JSON 贏的格子

引的論文是 Executable Code Actions Elicit Better LLM Agents(arXiv:2402.01030,ICML 2024)。摘要與引言的原話是 up to 20% higher success rate、up to a 20% absolute improvement over baselines on the success rate of solving the problems while requiring up to 30% fewer actions。

這個 20% 的條件要寫全:新做的 benchmark M3ToolEval,82 題,零樣本,最多 10 輪,成功率是答案與標準答案 exact match 的百分比;那個數字是 gpt-4-1106-preview 對文字格式的差距,單位是百分點;模型是 2023 到 2024 年的。論文附的 Table 3 是這樣(成功率 %,PDF v4 逐字抽出):

模型 CodeAct JSON 文字
gpt-4-1106-preview 74.4 52.4 53.7
gpt-4-0613 67.1 56.1 45.1
claude-2 54.9 39.0 29.3
gpt-3.5-turbo-0613 51.2 26.8 20.7
claude-instant-1 20.7 31.7 24.4
lemur-70b-chat-v1 13.4 15.9 12.2

上面四列 CodeAct 最高,下面兩列 JSON 最高。17 個模型裡,成功率最好的格式是 CodeAct 的有 12 個、JSON 5 個、文字 4 個(有並列,所以加起來超過 17)。論文自己對 JSON 有一段保留:開源模型上 JSON 一致偏弱,閉源模型上表現不差,推測是閉源模型對 JSON 做過針對性的微調。

另一張表更值得看。API-Bank 的原子工具呼叫(論文 Table 2),gpt-4-1106-preview 是 JSON 82.7、CodeAct 76.7;gpt-4-0613 是 JSON 82.0、CodeAct 75.4;gpt-3.5-turbo-1106 是 JSON 78.4、CodeAct 75.4。單一次呼叫、工具明確的時候,JSON 在這幾個閉源模型上不輸,甚至較高;同一張表裡 claude-2(CodeAct 76.7、JSON 59.4)和 claude-instant-1(75.2、64.9)則是 CodeAct 較高,所以不能說閉源模型一律偏愛 JSON。我的歸納是,CodeAct 的優勢出現在多工具組合、要控制流程與資料流的任務,跟官方「何時用哪個」的建議方向一致;這是我把兩邊並排的讀法,論文沒有這樣下結論。

還有一個數字要拆開。smolagents 的 README 寫 uses 30% fewer steps (thus 30% fewer LLM calls),連結指向同一篇論文。論文的原話是 up to 30% fewer actions,條件是上面那個 benchmark。README 那句少了 up to 也少了條件,所以不能當 smolagents 自己的實測數字,我也不引它。

組合的好處,吃得到的前提

CodeAgent 的「組合」並不是無條件的。我讀到的 v1.26.0 預設提示(官方 building_good_agents 頁貼出的縮短版)有兩條規則:

For tools WITHOUT JSON output schema: Take care to not chain too many sequential tool calls in the same code block, as their output format is unpredictable.
For tools WITH JSON output schema: You can confidently chain multiple tool calls and directly access structured output fields in the same code block!

意思是工具沒有輸出 schema 的時候,官方自己要求別串太多,先 print() 看輸出再下一步。迴圈那種寫法吃得最飽,是在工具輸出形狀可預期的時候。

code 也有自己的失敗型態。同一頁有個除錯例子:模型沒有把生成的影像存進變數,只回傳了路徑,官方的診斷是 the LLM brain did the mistake of not saving the image output into a variable。JSON 版根本不會有這種錯,因為它沒有變數可以忘記存。換句話說,「狀態持續存在」是優點,也是模型得自己管理的責任。

兩頁文件對「預設安全嗎」各說各的

這部分我不裁決,把兩句並排。

guided tour(v1.26.0):By default, the Python code execution is done in your local environment. This should be safe because the only functions that can be called are the tools you provided … and a set of predefined safe functions。

secure_code_execution:By default, the CodeAgent runs LLM-generated code in your environment. This is inherently risky, LLM-generated code could be harmful to your environment.

後一頁接著說明自建的 LocalPythonExecutor 是把程式碼解析成 AST、一個運算一個運算執行,預設禁止 import,運算次數設上限,沒定義過的運算一律報錯。同一頁的 WARNING 也講明:no local python sandbox can ever be completely secure,例子是放行 Pillow 之後,模型的程式可以產生成千上萬張大圖塞滿硬碟;真正穩固的隔離只有 E2B 或 Docker 這類遠端執行。文件列了 blaxel、e2b、modal、docker 四種 executor_type,並說明只把程式片段丟進沙箱的做法 doesn't support multi-agents,整個 agent 系統放進去則可能得把 API key 這類憑證也傳進沙箱。

JSON 那邊,guided tour 寫 no risk of arbitrary code running。這句只講「不會跑任意程式碼」,工具本身會做什麼,是另一個問題,官方沒有寫,這是我的補充。

先講清楚這篇的邊界。整篇是讀文件、原始碼樹和論文寫成的,我沒有安裝 smolagents,沒有跑過任何一個 CodeAgent 或 ToolCallingAgent,也沒有測過 LocalPythonExecutor 的防護或任何沙箱。CodeAgent 的提示取自官方文件頁貼出的 v1.26.0 縮短版(略過 zero-shot 範例),不是 code_agent.yaml 全文,原檔我只核對了範例那一行;structured_code_agent.yaml 我沒讀。intro_agents 另外引的兩篇論文我也沒讀,v1.5.0 到 v1.22.0 之間的 release notes 同樣沒讀,所以不知道兩種 agent 的預設在各版怎麼變。

我的取捨

專案現況先交代:截至 11 月 23 日,huggingface/smolagents 授權 Apache-2.0、30,484 顆星、沒有封存,11 月 20 日還有 push;最新 release 是 5 月 29 日的 v1.26.0,別把它讀成每週在發版的專案。

我的立場:「code 取代 JSON」這句話不成立,成立的是「多步組合、工具輸出可預期的任務,code 這邊比較有利,代價是你得準備執行環境」。單一原子呼叫、要嚴格驗證參數、或像瀏覽網頁那種每步都得等頁面反應的流程(官方 react 頁自己也說 JSON 在這裡 can fit well),我會選 JSON。

如果有人拿現在的模型,在多步任務上重做一次論文那種對照,結果 JSON 的成功率追平 code,我就會收回「code 較有利」這半句;論文的模型是 2023 到 2024 年的,我手上沒有今天模型的數字。另外,官方要是把兩頁對本地執行安全的說法統一、附上實測依據,我才會把「預設就能放心跑」或「預設一定危險」其中一句當作定論。

這是我自己的歸納,官方文件沒這樣寫:兩種做法換掉的是把關的位置。JSON 版把「這一步做什麼」交給模型、「這一步合不合法」交給 schema,驗證發生在動作送出之前;code 版把兩件事都收進模型寫的那段程式,驗證挪到執行的當下,由直譯器和沙箱接手。功能多寡反而是次要的,差別在出錯時誰先看到。想自己驗證,可以拿同一個三步任務各寫一版,數一數 LLM 呼叫次數與失敗型態;我沒做過這個實驗,上面所有數字都來自論文與官方文件。

原文來源:官方 intro_agents、guided tour(v1.26.0)、react、secure_code_execution、building_good_agents、toolcalling_agent.yaml(v1.26.0)、README、CodeAct 論文 arXiv:2402.01030