代理商 - 导游 - Smolagents

在本次指导访问中，您将学习如何构建代理、如何运行代理以及如何对代理进行定制，使其更好地满足您的用例需求。

建立您的代理 #

要初始化最小代理，至少需要这两个参数：

模型使用文本生成模型为代理提供动力--因为代理不同于简单的 LLM，它是一个使用 LLM 作为引擎的系统。您可以使用这些选项中的任何一个：
- 变形金刚模型会获取一个预初始化的 变压器 管道，在本地计算机上使用 变压器.
- HfApiModel 利用 huggingface_hub.InferenceClient 引擎盖下
- LiteLLMM 模型让您通过 LiteLLM!
工具，一份 工具 代理可以用来解决任务的问题。它可以是一个空列表。您也可以将默认工具箱添加到 工具 通过定义可选参数 add_base_tools=True.

一旦有了这两个参数、 工具 和 模型您可以创建并运行一个代理。您可以使用任何 LLM，无论是通过拥抱脸 API, 变压器, ollama或 LiteLLM.

拥抱脸 API

本地变压器模型

OpenAI 或人类应用程序接口

奥拉玛

Hugging Face API 无需令牌即可免费使用，但会有速率限制。

要使用专业版账户访问门控模型或提高费率限制，您需要设置环境变量 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(
    "你能给出斐波那契数列中的第 118 个数字吗？
)

代码代理和工具调用代理 #

"(《世界人权宣言》) 代码代理是我们的默认代理。它将在每个步骤中编写并执行 python 代码片段。

默认情况下，执行是在本地环境中进行的。这应该是安全的，因为能被调用的函数只有你提供的工具（特别是如果只有抱抱脸的工具）和一组预定义的安全函数，如 打印 或来自 算术 模块，因此执行的内容已经受到限制。

Python 解释器默认不允许安全列表之外的导入，因此所有最明显的攻击都不会有问题。您可以在参数 附加授权进口 在初始化您的代码代理:

复制的

模型 = 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 的广泛使用的方式：这就是工具呼叫代理它的工作原理与代码代理当然没有 附加授权进口 因为它不执行代码：

复制的

从 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.write_inner_memory_from_logs() 创建代理日志的内部存储器，供 LLM 以聊天信息列表的形式查看。该方法会查看日志的每一步，并只将感兴趣的内容存储为一条信息：例如，它会将系统提示和任务分别保存为不同的信息，然后将每一步的 LLM 输出存储为一条信息，将工具调用输出存储为另一条信息。如果你想从更高层次了解发生了什么，可以使用这种方法，但并不是所有日志都能用这种方法记录。

工具 #

工具是供代理使用的原子函数。要被 LLM 使用，它还需要一些属性，这些属性构成了它的 API，并将用于向 LLM 描述如何调用该工具：

一个名字
说明
输入类型和说明
输出类型

例如，您可以检查 PythonInterpreterTool：它有名称、描述、输入描述、输出类型和 转发 方法来执行操作。

当代理初始化时，工具属性会被用来生成工具描述，该描述会被嵌入代理的系统提示中。这可以让代理知道它可以使用哪些工具以及为什么。

默认工具箱 #

Transformers 自带一个用于授权代理的默认工具箱。 add_base_tools = True:

DuckDuckGo 网络搜索*目标：使用 DuckDuckGo 浏览器进行网络搜索。
Python 代码解释器LLM：在安全的环境中运行 LLM 生成的 Python 代码。该工具只会被添加到工具呼叫代理如果用 add_base_tools=True因为基于代码的代理已经可以本地执行 Python 代码
誊写员语音转文本：基于 Whisper-Turbo 的语音转文本管道，可将音频转录为文本。

您可以通过调用工具的参数来手动使用该工具。

复制的

从 smolagents 导入 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)

只需将这些代码封装到一个函数中并添加 工具 装饰器：这并不是构建工具的唯一方法：您可以直接将其定义为工具，这给了你更多的灵活性，例如初始化重类属性的可能性。

让我们来看看这两个选项是如何工作的：

用 @ 工具装饰函数

子类工具

复制的

从 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(
    "您能告诉我在抱抱脸枢纽的'文本到视频'任务中下载次数最多的模型名称吗？
)

您会收到以下日志：

复制的

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

│ 在 "抱抱脸枢纽 "上的任务？                                                            │
│ │
╰─ HfApiModel - Qwen/Qwen2.5-Coder-32B-Instruct ───────────────────────────────────────────╯
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━ 第 0 步 ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
╭─ 执行此代码：───────────────────────────────────────────────────────────────────╮
│ 1 model_name = model_download_tool(task="文本到视频") │ │ 2 print(model_name)
│ 2 print(model_name) │
╰──────────────────────────────────────────────────────────────────────────────────────────╯
执行日志：
ByteDance/AnimateDiff-Lightning

输出：无
[步骤 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.

为此，请将代理封装在一个托管代理对象。该对象需要参数 代理人, 名字和一个 描述会嵌入到管理代理的系统提示中，让它知道如何调用这个受管代理，我们对工具也是这样做的。

下面是一个制作代理的例子，该代理使用我们的 DuckDuc k 搜索工具:

复制的

from smolagents import CodeAgent, HfApiModel, DuckDuckGoSearchTool, ManagedAgent

模型 = 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 导入 (
    load_tool、
    代码代理
    HfApiModel、
    GradioUI
)

# 从枢纽中心导入工具
图像生成工具 = load_tool("m-ric/text-to-image")

模型 = HfApiModel(model_id)

# 使用图像生成工具初始化代理
agent = CodeAgent(tools=[image_generation_tool], model=model)

GradioUI(agent).launch()

在引擎盖下，当用户键入新答案时，代理会通过以下方式启动 agent.run(user_request, reset=False).......。 重置=假 这意味着在启动新任务之前，代理的内存不会被刷新，从而使对话得以继续。

您还可以使用 重置=假 参数，以便在任何其他代理应用程序中保持对话。

下一步工作 #

如需更深入的使用方法，请查看我们的教程：

开始

教程

概念指南

实例

代理 - 导游

建立您的代理 #

代码代理和工具调用代理 #

检查代理运行 #

工具 #

默认工具箱 #

创建新工具 #

多方代理 #

与您的代理对话，并在酷炫的 Gradio 界面中将其想法可视化 #

下一步工作 #

发表回复取消回复

建立您的代理 #

代码代理和工具调用代理 #

检查代理运行 #

工具 #

默认工具箱 #

创建新工具 #

多方代理 #

与您的代理对话，并在酷炫的 Gradio 界面中将其想法可视化 #

下一步工作 #

分享这篇文章 ：

发表回复 取消回复

分享这篇文章：

发表回复取消回复