Hugging Face smolagents 極簡開源代理教學:百行核心讓模型直接寫 Python 執行任務

Hugging Face 開源的 smolagents 主打極簡架構與 CodeAgent 模式,讓模型直接輸出 Python 程式碼呼叫工具而非繁瑣 JSON,一篇學會安裝與安全沙盒設定。

Share
smolagents官方 GitHub 專案封面圖:smolagents 教學
smolagents官方開源專案視覺圖。 圖片來源:官方原文。

很多工程師第一次接觸 AI 代理框架時,會被動輒數十層的抽象類別、複雜的狀態圖與冗長的設定檔搞得頭昏眼花。為了解決一個簡單的自動化任務,寫出來的膠水程式碼比業務邏輯還要長。

另一個更隱蔽的效能痛點是傳統的工具呼叫格式。大多數框架要求語言模型輸出一段結構嚴謹的 JSON 字串,而且一次通常只能呼叫一個工具。如果任務需要連續查詢五筆資料並做迴圈比對,模型就得來回呼叫五輪 API,既浪費時間又燒錢。

Hugging Face 開源的 smolagents 正是為了打破這個僵局。它的核心代理邏輯精簡到約莫一千行 Python 程式碼,主打 CodeAgent 模式,讓模型直接輸出可執行的 Python 片段來組合呼叫工具,將框架複雜度降到最低。

根據官方引用的論文實證數據,讓代理直接用程式碼表達行動,能比傳統 JSON 工具呼叫減少三成左右的推論步驟,在困難基準測試上也能獲得更高準確率。

這篇 smolagents 教學會帶你拆解 CodeAgent 的運作原理、安裝步驟與自訂工具寫法,並重點提醒本機執行與雲端沙盒隔離的資安邊界,避免把開發便利變成系統漏洞。

為什麼選擇寫 Python 而不是寫 JSON?拆解 CodeAgent 核心設計

要看懂這套極簡框架的價值,必須先對比它提供的兩種代理類別:CodeAgent 與 ToolCallingAgent。

傳統的 ToolCallingAgent 跟市面上多數框架一樣,讓模型輸出 JSON 或特定文字區塊,指定「我要呼叫哪個工具、傳入什麼參數」。這種做法看似安全,但模型無法在單一步驟裡使用變數暫存結果,也無法用 for 迴圈一次批次處理多個查詢。

更麻煩的是,當需要把前一個工具的輸出結果做字串切割或數值運算後,再餵給下一個工具時,傳統架構往往得耗費額外一輪模型推論才能完成轉換。

CodeAgent 的設計思路則完全不同。它把代理視為一位坐在 Python 直譯器前面的工程師,所有可用工具都只是預先匯入好的 Python 函式。當模型收到任務時,它會在 ReAct 思考與行動迴圈裡直接生成一段 Python 程式碼。

舉個實際例子,如果要同時搜尋三個不同主題的資料並印出結果,CodeAgent 只需要在同一個推論步驟裡寫出一個包含三個關鍵字的清單與 for 迴圈,呼叫三次 web_search 函式就能一次完成。這直接省下了好幾輪昂貴的模型往復等待時間。

除了極簡的核心邏輯,這套工具在整合面上也保持高度彈性:

  • 模型無關性:透過 InferenceClientModel 可以串接 Hugging Face 推論服務,也可以用 LiteLLMModel 呼叫 OpenAI、Anthropic 等數十家商業 API,或是用 TransformersModel 與 Ollama 跑本地開源模型。
  • 工具生態相容:支援 @tool 裝飾器快速建立函式工具,也能透過 ToolCollection.from_mcp 掛載任何 MCP 伺服器,或是直接從 LangChain 與 Hugging Face Hub Spaces 匯入現成工具。
  • 多模態支援:除了純文字任務,代理也能處理圖片、視覺網頁操作甚至音訊與影片輸入,滿足跨模態自動化需求。
smolagents官方 GitHub 專案封面圖:smolagents 教學
smolagents官方開源專案視覺圖。 圖片來源:官方原文。

安裝步驟、CLI 指令與第一個實戰範例

這套套件的安裝非常輕量。如果希望直接取得預設的常用工具套件組合,可以在終端機執行以下指令安裝:

pip install "smolagents[toolkit]"

如果你想直接透過終端機命令列快速體驗,安裝後系統也會附上 smolagent 與 webagent 兩個內建 CLI 指令。

只要直接輸入 smolagent,就會進入互動式設定精靈,引導你挑選代理類型、模型供應商與內建工具;如果想快速驗證網頁瀏覽代理,也可以直接使用 webagent 指令搭配目標網址與任務描述。

在 Python 程式開發裡,建立一個具備網路搜尋能力的 CodeAgent 只需要不到十行程式碼。以下示範官方最經典的快速入門寫法:

from smolagents import CodeAgent, WebSearchTool, InferenceClientModel

model = InferenceClientModel()
agent = CodeAgent(tools=[WebSearchTool()], model=model, stream_outputs=True)

agent.run("How many seconds would it take for a leopard at full speed to run through Pont des Arts?")

在這段程式碼裡,代理收到問題後會自動規劃拆解。它會先用 WebSearchTool 查詢獵豹的最高奔跑速度與巴黎藝術橋的長度,接著自己寫出 Python 除法運算得出秒數,最後呼叫內建的 final_answer 工具回傳精確答案。

如果你想改用自己的 OpenAI 或 Anthropic 金鑰,或是串接本地模型,只要把 model 替換成 LiteLLMModel 即可:

from smolagents import CodeAgent, LiteLLMModel, WebSearchTool

model = LiteLLMModel(model_id="anthropic/claude-3-7-sonnet-20250219")
agent = CodeAgent(tools=[WebSearchTool()], model=model)

透過這樣的抽象層設計,開發者在切換測試模型與正式環境模型時,幾乎不需要重寫任何代理邏輯。

自訂工具定義與 MCP 伺服器串接指南

在實務專案中,我們通常需要讓代理讀取內部資料庫或呼叫公司 API。在這裡定義自訂工具最簡單的方式是使用 @tool 裝飾器。

撰寫自訂工具時,務必寫清楚型別標註與文件字串,因為框架會把這些資訊自動轉成給模型看的函式說明與參數規格:

from smolagents import CodeAgent, InferenceClientModel, tool

@tool
def get_inventory_count(sku: str) -> int:
    """
    查詢指定商品編號的目前庫存數量。

    Args:
        sku: 商品的唯一庫存識別碼,例如 'SKU-1024'。
    """
    inventory = {"SKU-1024": 42, "SKU-2048": 0}
    return inventory.get(sku, 0)

agent = CodeAgent(tools=[get_inventory_count], model=InferenceClientModel())
agent.run("請幫我確認 SKU-1024 還有多少庫存?")

除了自己寫 Python 函式,這個框架也原生支援從 MCP 伺服器載入工具集。當團隊已經把資料庫查詢、Git 操作或檔案系統封裝成標準 MCP 服務時,代理就能直接取用這些能力,不需要為不同框架重複撰寫工具包裝層。

另外一個相當實用的生態功能是社群分享。如果你寫好了一個實用的代理組合,可以呼叫 push_to_hub 方法直接分享到 Hugging Face Hub,讓其他開發者用一行 from_hub 函式載入重複使用,大幅加速團隊內部的工具複用。

延伸閱讀:加州檢察長控告 OpenAI:700 個 AI 代理逃出沙盒入侵 Hugging Face,訴訟焦點與責任爭議全解析

CodeAgent 與傳統代理架構對比

為了讓你在技術選型時更清楚取捨,以下整理 CodeAgent、ToolCallingAgent 與大型編排框架之間的差異:

比較項目 smolagents CodeAgent smolagents ToolCallingAgent 傳統大型編排框架
代理行動表達方式 直接輸出 Python 程式碼片段 輸出標準 JSON 或工具呼叫結構 依賴圖節點狀態與 JSON 工具規格
多步驟迴圈與運算 原生在單次動作內用迴圈與變數處理 每次工具呼叫通常需耗費一輪 LLM 推論 需靠開發者預先寫死流程或多次來回
核心程式碼學習成本 極低,核心邏輯約千行,容易直接讀懂 極低,概念與各家標準工具呼叫相同 較高,需理解圖引擎、狀態機與多種抽象
執行安全性要求 極高,必須搭配沙盒隔離不信任程式碼 中等,僅限預先定義好的工具參數執行 視工具權限而定,通常不執行任意生成碼
最適合的應用場景 資料分析、數學計算、多步驟動態工具組合 參數固定、高度受控的單純 API 觸發 複雜企業長流程、多角色審核與持久化狀態

資安邊界與警告:千萬別把 LocalPythonExecutor 當成安全沙盒

使用這套極簡框架時,有一條官方文件特別用粗體強調的資安紅線:內建的 LocalPythonExecutor 絕對不是安全沙盒。

雖然 LocalPythonExecutor 在本機執行模型生成的程式碼時,會限制只能匯入白名單內的模組,並做了一些語法樹層級的檢查,但它本質上還是運行在你的主機 Python 程序裡。

根據安全研究與官方警告,這種純 Python 層級的限制存在被繞過的風險,因此絕對不能作為阻擋惡意程式碼或提示詞注入的防線。

當你把代理部署到線上環境,或是讓代理處理來自外部網頁、使用者上傳文件等不信任輸入時,正確的做法是把程式碼執行環境完全隔離出去。框架原生支援多種真正的沙盒後端:

  • 雲端微虛擬機與容器服務:直接整合 E2B、Blaxel 與 Modal,這是最容易上手且隔離強度最高的方案。即使模型生成了破壞性指令,也只會在獨立的雲端沙盒裡爆發,完全碰不到你的主機網路與檔案系統。
  • 自架 Docker 容器:如果基於合規要求不能使用外部雲端沙盒,可以把程式碼執行器切換為本機或內網的 Docker 容器環境,並搭配唯讀掛載與無網路權限設定來縮小風險。

另一項常見限制是「模型寫碼能力門檻」。因為 CodeAgent 高度依賴模型寫出語法正確的 Python 程式碼與正確處理錯誤例外,如果你選用參數量過小、沒有針對程式設計最佳化的模型,執行過程很容易不斷出現語法錯誤而重試。遇到模型程式能力較弱的情況,建議直接切換回 ToolCallingAgent,整體穩定度會高出許多。

延伸閱讀:Apple 宣布 macOS 27.3 拆分裝置控制與資料存取權限:AI 代理時代的 Mac 資安新防線

進階開發速查:多代理協作、記憶管理與 CLI 實戰技巧

當單一代理無法應付複雜的長流程任務時,這套極簡框架也提供了一套非常乾淨的擴充手段,讓你能用最少程式碼搭建階層式團隊與自動化腳本。

首先是「管理員與子代理的階層編排」。你可以先建立一個專門負責網路調查的搜尋代理,再建立一個專門負責撰寫報告或清理資料的分析代理,最後透過 managed_agents 參數把它們交給上層管理員代理統一調度。

這種拆法的好處是職責分離且上下文乾淨。每個子代理只需要看懂自己手邊的工具與短提示詞,執行完畢後只把精煉過的結論回傳給管理員,大幅降低單一上下文視窗塞爆的機率。

其次是「步驟上限與執行控制」。在撰寫自動化腳本時,務必在初始化 CodeAgent 時設定 max_steps 參數限制最大思考迴圈次數。這能防止模型在遇到無法解決的外部 API 錯誤時陷入死胡同,白白燒掉大量推論費用。

此外,對於想快速驗證網頁自動化的開發者,內建的 webagent 命令列工具結合了 Helium 瀏覽器操作封裝與視覺理解能力,可以直接從終端機下達自然語言指令去操作網頁並擷取價格或商品資訊。

最後在除錯階段,建議保持 stream_outputs=True 串流輸出設定,並搭配詳細日誌觀察模型每一輪產生的 Python 程式碼片段。一旦發現模型反覆在某個函式呼叫上出現型別錯誤,通常只要補清楚該工具的文件字串說明與範例格式,就能立刻消除卡關問題。

在實務上線前,也建議團隊檢查三件事:第一,確認所有對外服務的代理都已切換至獨立容器或雲端沙盒,避免使用預設的本機直譯器執行未知來源程式碼。第二,把敏感 API 金鑰與資料庫連線字串透過工具層封裝管理,不要直接暴露在模型可讀取的環境變數裡。第三,針對常見任務建立自動化評估腳本,定期追蹤不同模型版本在寫碼成功率與總花費步驟數上的變化。

常見問題

這份 smolagents 教學介紹的框架跟 LangGraph 或 CrewAI 相比,優勢是什麼?

最大的優勢是極簡與透明。這個框架沒有厚重的抽象層,開發者花十幾分鐘就能直接讀懂原始碼。加上 CodeAgent 讓模型直接寫 Python 組合工具,在需要動態運算與迴圈處理的任務上,步驟更少也更容易除錯。

使用 CodeAgent 需要手動開啟哪些函式庫的匯入權限嗎?

需要。出於最基本的防護,預設執行器只允許匯入基本的安全內建模組。如果你的任務需要讓模型在生成的程式碼裡使用 pandas、numpy 或 requests,必須在初始化 CodeAgent 時透過 additional_authorized_imports 參數明確列出允許匯入的清單。

在本機開發測試時,一定要申請 E2B 或 Modal 沙盒帳號嗎?

在單純測試自己寫的信任資料、不接觸外部未知網頁時,本機預設執行器可以讓你快速驗證邏輯。但只要準備對外提供服務、或讓代理讀取網路公開網頁與用戶輸入,就強烈建議切換到 Docker 或 E2B 等隔離沙盒環境。

這套極簡框架支援多代理互相協作嗎?

支援。你可以把一個配置好專屬工具與系統提示詞的代理包裝成管理員底下的子代理,透過 managed_agents 參數交給主代理調度。這讓團隊可以用很乾淨的階層結構拆分研究代理與寫碼代理,同時維持極簡的程式碼架構。

結語

Hugging Face smolagents 為 AI 代理開發提供了一股清流。它證明了把控制權交回給 Python 語言本身,往往比堆疊複雜的框架抽象更有效率,也更貼近工程師的直覺。

適合誰:偏好簡潔 Python 程式碼、需要讓代理處理資料分析、多步驟邏輯運算,而且願意自行把關執行沙盒隔離的工程師與研究人員。

不適合誰:需要內建視覺化流程拖拉介面、企業級持久化狀態恢復引擎,或是只想讓非工程背景人員透過純設定檔操作多代理團隊的組織。

想獲得更多開源 AI 代理框架的架構拆解、實戰程式碼與資安避坑指南,歡迎立即免費訂閱 AI 郵報,每週精選最實用的開發工具直送信箱。

資料來源