smolagents 文档
智能体 - 引导式游览
并获得增强的文档体验
开始使用
智能体 - 引导式游览
在本引导式访问中，您将学习如何构建智能体、如何运行它以及如何自定义它以使其更好地适用于您的用例。
构建您的智能体
要初始化一个最小的智能体，您至少需要这两个参数
model，一个文本生成模型，为您的智能体提供动力 - 因为智能体不同于简单的 LLM，它是一个使用 LLM 作为其引擎的系统。您可以使用以下任何选项- TransformersModel 接受预初始化的
transformers管道，以使用transformers在您的本地机器上运行推理。 - HfApiModel 在底层利用
huggingface_hub.InferenceClient，并支持 Hub 上的所有推理提供商。 - LiteLLMModel 同样允许您通过 LiteLLM 调用 100 多个不同的模型和提供商！
- AzureOpenAIServerModel 允许您使用部署在 Azure 中的 OpenAI 模型。
- MLXModel 创建一个 mlx-lm 管道，以在您的本地机器上运行推理。
- TransformersModel 接受预初始化的
tools，智能体可以用来解决任务的Tools列表。它可以是一个空列表。您还可以通过定义可选参数add_base_tools=True在您的tools列表之上添加默认工具箱。
一旦您有了这两个参数 tools 和 model，您就可以创建一个智能体并运行它。您可以使用任何您喜欢的 LLM，可以通过 推理提供商、transformers、ollama、LiteLLM、Azure OpenAI 或 mlx-lm。
HF 推理 API 可以免费使用，无需令牌，但会受到速率限制。
要访问门控模型或提高 PRO 帐户的速率限制，您需要设置环境变量 HF_TOKEN 或在初始化 HfApiModel 时传递 token 变量。您可以从您的 设置页面 获取您的令牌
from smolagents import CodeAgent, HfApiModel
model_id = "meta-llama/Llama-3.3-70B-Instruct"
model = HfApiModel(model_id=model_id, token="<YOUR_HUGGINGFACEHUB_API_TOKEN>") # You can choose to not pass any model_id to HfApiModel to use a default free model
# you can also specify a particular provider e.g. provider="together" or provider="sambanova"
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 的工具）和一组预定义的安全函数，如 print 或来自 math 模块的函数，因此您已经限制了可以执行的内容。
Python 解释器默认也不允许从安全列表之外导入，因此所有最明显的攻击都不应该成为问题。您可以通过在初始化您的 CodeAgent 时，将授权模块作为字符串列表在参数 additional_authorized_imports 中传递来授权其他导入
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 代码执行器 或 Docker 代替本地 Python 解释器。对于 E2B，首先设置 E2B_API_KEY 环境变量，然后在代理初始化时传递 executor_type="e2b"。对于 Docker，在初始化期间传递 executor_type="docker"。
了解有关代码执行的更多信息，请参阅本教程。
我们还支持将操作编写为类似 JSON blob 的广泛使用方式：这就是 ToolCallingAgent，它的工作方式与 CodeAgent 非常相似，当然没有 additional_authorized_imports，因为它不执行代码
from smolagents import 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_memory_to_messages()将智能体的记忆作为聊天消息列表写入，供模型查看。此方法遍历日志的每一步，并且仅存储它感兴趣的内容作为消息：例如，它将系统提示和任务保存在单独的消息中，然后对于每一步，它将 LLM 输出存储为一条消息，并将工具调用输出存储为另一条消息。如果您想要更高级别地查看发生了什么 - 但并非每个日志都会通过此方法转录，请使用此方法。
工具
工具是智能体要使用的原子函数。要被 LLM 使用，它还需要一些属性来构成其 API，并将用于向 LLM 描述如何调用此工具
- 名称
- 描述
- 输入类型和描述
- 输出类型
例如，您可以查看 PythonInterpreterTool：它具有名称、描述、输入描述、输出类型和执行操作的 forward 方法。
当初始化智能体时，工具属性用于生成工具描述，该描述被烘焙到智能体的系统提示中。这让智能体知道它可以使用哪些工具以及原因。
默认工具箱
smolagents 配备了一个默认工具箱，用于增强智能体的能力，您可以通过参数 add_base_tools = True 在初始化时将其添加到您的智能体中
- DuckDuckGo 网络搜索*：使用 DuckDuckGo 浏览器执行网络搜索。
- Python 代码解释器：在安全环境中运行您的 LLM 生成的 Python 代码。如果您使用
add_base_tools=True初始化 ToolCallingAgent，则此工具将仅添加到其中，因为基于代码的智能体已经可以原生执行 Python 代码 - 转录器：一个基于 Whisper-Turbo 构建的语音转文本管道，可将音频转录为文本。
您可以通过使用工具的参数调用工具来手动使用工具。
from smolagents import DuckDuckGoSearchTool
search_tool = DuckDuckGoSearchTool()
print(search_tool("Who's the current president of Russia?"))创建新工具
您可以创建自己的工具，用于 Hugging Face 的默认工具未涵盖的用例。例如，让我们创建一个工具，该工具返回 Hub 中给定任务下载次数最多的模型。
您将从下面的代码开始。
from huggingface_hub import list_models
task = "text-classification"
most_downloaded_model = next(iter(list_models(filter=task, sort="downloads", direction=-1)))
print(most_downloaded_model.id)只需将其包装在一个函数中并添加 tool 装饰器，即可将此代码快速转换为工具：这不是构建工具的唯一方法：您可以直接将其定义为 Tool 的子类，这将为您提供更大的灵活性，例如初始化重类属性的可能性。
让我们看看它如何适用于这两种选项
from smolagents import tool
@tool
def model_download_tool(task: str) -> str:
"""
This is a tool that returns the most downloaded model of a given task on the Hugging Face Hub.
It returns the name of the checkpoint.
Args:
task: The task for which to get the download count.
"""
most_downloaded_model = next(iter(list_models(filter=task, sort="downloads", direction=-1)))
return most_downloaded_model.id该函数需要
- 一个清晰的名称。名称应充分描述此工具的功能，以帮助为智能体提供动力的 LLM 大脑。由于此工具返回任务下载次数最多的模型，因此我们将其命名为
model_download_tool。 - 输入和输出的类型提示
- 描述，其中包含一个“Args:”部分，其中描述了每个参数（这次没有类型指示，它将从类型提示中提取）。与工具名称相同，此描述是为您的智能体提供动力的 LLM 的说明手册，因此请勿忽略它。所有这些元素都将在初始化时自动烘焙到智能体的系统提示中：因此，请力求使其尽可能清晰！
此定义格式与 apply_chat_template 中使用的工具模式相同，唯一的区别是添加了 tool 装饰器：在此处阅读有关我们的工具使用 API 的更多信息 here。
然后您可以直接初始化您的智能体
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 ─────────────────────────────────────────╮
│ │
│ 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? │
│ │
╰─ HfApiModel - Qwen/Qwen2.5-Coder-32B-Instruct ───────────────────────────────────────────╯
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━ Step 0 ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
╭─ Executing this code: ───────────────────────────────────────────────────────────────────╮
│ 1 model_name = model_download_tool(task="text-to-video") │
│ 2 print(model_name) │
╰──────────────────────────────────────────────────────────────────────────────────────────╯
Execution logs:
ByteDance/AnimateDiff-Lightning
Out: None
[Step 0: Duration 0.27 seconds| Input tokens: 2,069 | Output tokens: 60]
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━ Step 1 ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
╭─ Executing this code: ───────────────────────────────────────────────────────────────────╮
│ 1 final_answer("ByteDance/AnimateDiff-Lightning") │
╰──────────────────────────────────────────────────────────────────────────────────────────╯
Out - Final answer: ByteDance/AnimateDiff-Lightning
[Step 1: Duration 0.10 seconds| Input tokens: 4,288 | Output tokens: 148]
Out[20]: 'ByteDance/AnimateDiff-Lightning'在 专用教程 中阅读有关工具的更多信息。
多智能体
多智能体系统已通过 Microsoft 的框架 Autogen 引入。
在这种类型的框架中，您有多个智能体协同工作来解决您的任务，而不是只有一个。它在大多数基准测试中经验性地产生了更好的性能。这种更好性能的原因在概念上很简单：对于许多任务，与其使用万能系统，您更愿意专门化子任务的单元。在这里，拥有具有单独工具集和记忆的智能体可以实现高效的专业化。例如，为什么要用网络搜索智能体访问的网页的所有内容来填充代码生成智能体的记忆呢？最好将它们分开。
您可以使用 smolagents 轻松构建分层多智能体系统。
为此，只需确保您的智能体具有 name 和 description 属性，然后将其嵌入到管理器智能体的系统提示中，以使其知道如何调用此受管理的智能体，就像我们对工具所做的那样。然后，您可以将此受管理的智能体在管理器智能体的初始化时传递到参数 managed_agents 中。
这是一个示例，说明如何创建一个管理特定网络搜索智能体的智能体，该智能体使用我们的 DuckDuckGoSearchTool
from smolagents import CodeAgent, HfApiModel, DuckDuckGoSearchTool
model = HfApiModel()
web_agent = CodeAgent(
tools=[DuckDuckGoSearchTool()],
model=model,
name="web_search",
description="Runs web searches for you. Give it your query as an argument."
)
manager_agent = CodeAgent(
tools=[], model=model, managed_agents=[web_agent]
)
manager_agent.run("Who is the CEO of Hugging Face?")有关高效多智能体实现的深入示例，请参阅 我们如何将多智能体系统推向 GAIA 排行榜的榜首。
与您的智能体对话并在酷炫的 Gradio 界面中可视化其想法
您可以使用 GradioUI 以交互方式向您的智能体提交任务并观察其思考和执行过程，这是一个示例
from smolagents import (
load_tool,
CodeAgent,
HfApiModel,
GradioUI
)
# Import tool from Hub
image_generation_tool = load_tool("m-ric/text-to-image", trust_remote_code=True)
model = HfApiModel(model_id=model_id)
# Initialize the agent with the image generation tool
agent = CodeAgent(tools=[image_generation_tool], model=model)
GradioUI(agent).launch()在底层，当用户键入新答案时，智能体将使用 agent.run(user_request, reset=False) 启动。 reset=False 标志表示在启动此新任务之前，智能体的记忆不会被清除，这使对话得以继续进行。
您还可以使用此 reset=False 参数来保持任何其他智能体应用程序中的对话继续进行。
在 gradio UI 中，如果您想允许用户中断正在运行的智能体，您可以使用一个按钮来触发方法 agent.interrupt()。这将使智能体在其当前步骤结束时停止，然后引发错误。
下一步
最后，当您根据自己的需求配置好智能体后，您可以将其共享到 Hub！
agent.push_to_hub("m-ric/my_agent")同样，要加载已推送到 hub 的智能体，如果您信任其工具的代码，请使用
agent.from_hub("m-ric/my_agent", trust_remote_code=True)要获得更深入的用法，您接下来需要查看我们的教程
< > 在 GitHub 上更新