代理商 - 導覽 - Smolagents

在此導覽中，您將學習如何建立代理程式、如何執行代理程式，以及如何自訂代理程式使其更適合您的使用情況。

建立您的代理 #

要初始化最小代理，您至少需要這兩個參數：

模型, 一個文本生成模型來為您的代理提供動力 - 因為代理不同於簡單的 LLM，它是一個使用 LLM 作為引擎的系統。您可以使用其中任何一個選項：
- 變形金剛模型需要一個預初始化的 變壓器 管道在本機上執行推理，使用 變壓器.
- HfApiModel 利用 huggingface_hub.InferenceClient 在引擎蓋下。
- LiteLLMM 模型讓您透過 LiteLLM!
工具,清單 工具 代理可以用來解決任務。它可以是一個空清單。您也可以將預設的工具箱加在您的 工具 透過定義可選參數 add_base_tools=True.

一旦您有了這兩個論點、 工具 和 模型, 您可以建立一個代理程式並執行它。您可以使用任何您想要的 LLM，無論是透過擁抱臉 API, 變壓器, ollama或 LiteLLM.

擁抱臉 API

本地變壓器模型

OpenAI 或人類 API

Ollama

Hugging Face API 不需要令牌即可免費使用，但會有速率限制。

若要使用 PRO 帳戶存取門控模型或提高費率限制，您需要設定環境變數 HF_TOKEN 或通過 符記 變數初始化時 HfApiModel.

複製

from smolagents import CodeAgent, HfApiModel

model_id = "meta-llama/Llama-3.3-70B-Instruct"

model = HfApiModel(model_id=model_id, token="")
agent = CodeAgent(tools=[], model=model, add_base_tools=True)

agent.run(
    "Could you give me the 118th number in the Fibonacci sequence?"、
)

CodeAgent 和 ToolCallingAgent #

的 CodeAgent 是我們的預設代理程式。它會在每個步驟中寫入並執行 python 程式碼片段。

預設是在您的本機環境中執行。這應該是安全的，因為能被呼叫的函數只有您提供的工具 (特別是只有 Hugging Face 的工具) 和一組預先定義的安全函數，例如 列印 或功能從 數學 模組，所以您在執行上已經受到限制。

Python 解譯器也不允許在安全清單之外的預設匯入，所以所有最明顯的攻擊應該都不是問題。您可以將授權的模組以字串的方式傳給參數 額外的授權進口 在初始化您的 CodeAgent:

複製

model = HfApiModel()
agent = CodeAgent(tools=[], model=model, additional_authorized_imports=['requests', 'bs4'])
agent.run("Could you get me the title of the page at url 'https://huggingface.co/blog'?")

LLM 可以產生隨後執行的任意程式碼：請勿加入任何不安全的匯入！

當任何程式碼嘗試執行非法操作，或代理程式產生的程式碼出現一般 Python 錯誤時，執行就會停止。

您也可以使用 E2B 代碼執行器而不是本機 Python 解譯器，方法是先使用設定 E2B_API_KEY 環境變數然後將 use_e2b_executor=True 在代理初始化時。

進一步瞭解代碼執行在本教程中.

我們也支援廣泛使用的方式，將動作書寫為類似 JSON 的 blob：這是工具呼叫代理，其運作方式與 CodeAgent當然沒有 額外的授權進口 因為它不會執行程式碼：

複製

從 smolagents 匯入 ToolCallingAgent

agent = ToolCallingAgent(tools=[], model=model)
agent.run("Could you get me the title of the page at url 'https://huggingface.co/blog'?")

檢查代理程式執行 #

以下是一些有用的屬性，可檢查運行後發生的事情：

agent.logs 儲存代理的精細記錄。在代理運行的每一步驟中，所有內容都會儲存在字典中，然後被追加到 agent.logs.
運行 agent.write_inner_memory_from_logs() 建立代理日誌的內部記憶體，供 LLM 檢視，作為聊天訊息清單。此方法會檢視日誌的每個步驟，並只將其感興趣的內容儲存為訊息：例如，它會將系統提示和任務分別儲存為不同的訊息，然後每一步驟都會將 LLM 輸出儲存為訊息，並將工具呼叫輸出儲存為另一個訊息。如果您想要對所發生的事情有更高層次的檢視，請使用這個方法 - 但不是每個記錄都會用這個方法來記錄。

工具 #

工具是代理使用的原子函數。要被 LLM 使用，它還需要一些屬性，這些屬性構成了它的 API，並將用來向 LLM 描述如何呼叫此工具：

名稱
說明
輸入類型和說明
輸出類型

例如，您可以檢查 PythonInterpreterTool：它有一個名稱、描述、輸入描述、輸出類型和 前言 方法來執行動作。

當代理程式初始化時，工具屬性會被用來產生一個工具描述，這個工具描述會被植入代理程式的系統提示中。這可讓代理程式知道它可以使用哪些工具，以及使用的原因。

預設工具箱 #

Transformers 隨附一個預設的工具箱，用來賦予代理權力，您可以在初始化時將它加入代理，並使用參數 add_base_tools = True:

DuckDuckGo 網路搜尋*：使用 DuckDuckGo 瀏覽器執行網路搜尋。
Python 程式碼解譯器：在安全的環境中執行您的 LLM 所產生的 Python 程式碼。這個工具只會被加入到工具呼叫代理如果您用 add_base_tools=True, 因為基於代碼的代理已經可以本機執行 Python 代碼
謄寫員：建立在 Whisper-Turbo 上的語音轉文字管道，可將音訊轉錄為文字。

您可以手動使用工具，方法是使用工具的參數來呼叫它。

複製

from smolagents import DuckDuckGoSearchTool

search_tool = DuckDuckGoSearchTool()
print(search_tool("Who's the current president of Russia?"))

建立新工具 #

您可以針對 Hugging Face 預設工具未涵蓋的使用個案，建立自己的工具。例如，讓我們建立一個工具，從 Hub 傳回給定任務下載最多的模型。

您將從下面的程式碼開始。

複製

從 huggingface_hub 匯入 list_models

任務 = 「文字分類」

most_downloaded_model = next(iter(list_models(filter=task, sort="downloads",direction=-1)))
print(most_downloaded_model.id)

這些程式碼可以快速轉換成工具，只要將它包裝成函式，並加入 工具 裝飾器：這不是建立工具的唯一方法：您可以直接將它定義為工具，讓您有更多彈性，例如可以初始化重類屬性。

讓我們看看這兩個選項是如何運作的：

使用 @tool 來裝飾函數

子類工具

複製

從 smolagents 匯入工具

@tool
def model_download_tool(task: str) -> str：
    """
    這是一個工具，用來回傳 Hugging Face Hub 上指定任務最常下載的模型。
    它會返回檢查點的名稱。

    Args：
        任務：要取得下載次數的任務。
    """
    most_downloaded_model = next(iter(list_models(filter=task, sort="downloads", direction=-1)))
    return most_downloaded_model.id

功能需求：

清晰的名稱。這個名稱應該足以描述這個工具的功能，以協助 LLM 腦部為代理程式提供動力。由於這個工具會回傳一個任務中下載次數最多的模型，所以我們將它命名為 模型下載工具.
輸入和輸出的類型提示
描述，其中包括「Args:」部分，描述每個參數（這次沒有類型指示，會從類型提示中取得）。與工具名稱一樣，此描述是為您的代理程式提供動力的 LLM 的說明手冊，因此請勿忽略。所有這些元素都會在初始化時自動納入代理程式的系統提示中：因此請盡可能讓它們清楚明瞭！

此定義格式與在 套用聊天範本，唯一的差別是增加了 工具 裝飾器：詳細閱讀我們的工具使用 API 這裡.

之後您就可以直接初始化您的代理程式：

複製

from smolagents import CodeAgent, HfApiModel
agent = CodeAgent(tools=[model_download_tool], model=HfApiModel())
agent.run(
    "Can you give me the name of the model that has the most downloads in the 'text-to-video' task on the Hugging Face Hub?" "您能告訴我在抱抱臉樞紐的「文字轉影片」任務中，下載次數最多的模型名稱嗎？
)

您會得到以下記錄：

複製

╭──────────────────────────────────────── New run ─────────────────────────────────────────╮
│ │

│ Hugging Face Hub 上的任務？                                                            │
│ │
╰─ HfApiModel - Qwen/Qwen2.5-Coder-32B-Instruct ───────────────────────────────────────────╯
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━ 步驟 0 ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
╭─ 執行此程式碼：───────────────────────────────────────────────────────────────────╮
│ 1 model_name = model_download_tool(task="text-to-video") │ │ 2 print(model_name)
│ 2 print(model_name) │
╰──────────────────────────────────────────────────────────────────────────────────────────╯
執行記錄：
ByteDance/AnimateDiff-Lightning

輸出：無
[Step 0: Duration 0.27 seconds| Input tokens: 2,069 | Output tokens: 60] [步驟 0：持續時間 0.27 秒| 輸入代幣：2,069 | 輸出代幣：60
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━ 步驟 1 ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
╭─執行這段程式碼：───────────────────────────────────────────────────────────────────╮
│ 1 final_answer("ByteDance/AnimateDiff-Lightning")│。
╰──────────────────────────────────────────────────────────────────────────────────────────╯
Out - 最終答案：ByteDance/AnimateDiff-Lightning
[Step 1: Duration 0.10 seconds| Input tokens: 4,288 | Output tokens: 148] [步驟 1: 時間 0.10 秒| 輸入符號：4,288 | 輸出符號：148
Out[20]: "ByteDance/AnimateDiff-Lightning

閱讀更多關於工具的資訊專用教學.

多重代理 #

多代理系統已被引入微軟的框架 Aut o 基因.

在這類型的架構中，您有數個代理共同解決您的任務，而不是只有一個代理。根據經驗，它在大多數的基準上都有更好的效能。效能較佳的原因在概念上很簡單：對於許多任務而言，與其使用萬能系統，您更願意專精於子任務上的單元。在此，讓代理擁有獨立的工具集和記憶體，可以達到有效率的專業化。例如，為什麼要在程式碼產生代理的記憶體中填滿網頁搜尋代理所瀏覽的所有網頁內容？最好將它們分開。

您可以使用 smolagents.

為此，請將代理封裝在 ManagedAgent 物件。此物件需要參數 代理, 姓名和一個 描述，然後嵌入管理員代理的系統提示中，讓它知道如何呼叫此管理代理，就像我們對工具所做的一樣。

下面是一個製作代理程式的範例，這個代理程式使用我們的鴨子 k GoSearchTool:

複製

from smolagents import CodeAgent, HfApiModel, DuckDuckGoSearchTool, ManagedAgent

model = HfApiModel()

web_agent = CodeAgent(tools=[DuckDuckGoSearchTool()], model=model)

managed_web_agent = ManagedAgent(
    agent=web_agent、
    name="web_search"、
    description="為您執行網路搜尋。將您的查詢作為參數給它"。
)

manager_agent = CodeAgent(
    tools=[], model=model, managed_agents=[managed_web_agent]
)

manager_agent.run("Who is the CEO of Hugging Face?")

有關高效率多機體實作的深入範例，請參閱我們如何將我們的多機器人系統推向 GAIA 排行榜的頂端.

在酷炫的 Gradio 介面中與您的代理交談，並視覺化其想法 #

您可以使用 GradioUI 以互動方式向您的代理提交任務，並觀察它的思考和執行過程，以下是一個範例：

複製

從 smolagents import (
    load_tool、
    CodeAgent、
    HfApiModel、
    GradioUI
)

# 從 Hub 匯入工具
image_generation_tool = load_tool("m-ric/text-to-image")

model = HfApiModel(model_id)

# 使用影像產生工具初始化代理程式
agent = CodeAgent(tools=[image_generation_tool], model=model)

GradioUI(agent).launch()

在引擎蓋下，當使用者輸入新的答案時，代理程式會以下列方式啟動 agent.run(user_request, reset=False).......。 重設=假 flag 表示代理程式的記憶體在啟動這項新任務前不會被刷新，這可讓對話繼續進行。

您也可以使用此 重設=假 論點，讓對話在任何其他代理應用程式中持續進行。

接下來的步驟 #

如需更深入的使用方法，請參閱我們的教學：

開始

教學

概念指南

範例

代理商 - 導覽

建立您的代理 #

CodeAgent 和 ToolCallingAgent #

檢查代理程式執行 #

工具 #

預設工具箱 #

建立新工具 #

多重代理 #

在酷炫的 Gradio 介面中與您的代理交談，並視覺化其想法 #

接下來的步驟 #

發佈留言取消回覆

建立您的代理 #

CodeAgent 和 ToolCallingAgent #

檢查代理程式執行 #

工具 #

預設工具箱 #

建立新工具 #

多重代理 #

在酷炫的 Gradio 介面中與您的代理交談，並視覺化其想法 #

接下來的步驟 #

分享這篇文章 ：

發佈留言 取消回覆

分享這篇文章：

發佈留言取消回覆