smolagents：一个用于构建代理的简单库

HF推出 smolagents，一个非常简单的库，它能够解锁语言模型的代理功能。以下是它的简要介绍：

from smolagents import CodeAgent, DuckDuckGoSearchTool, HfApiModelagent = CodeAgent(tools=[DuckDuckGoSearchTool()], model=HfApiModel())agent.run("How many seconds would it take for a leopard at full speed to run through Pont des Arts?")

目录

• 🤔 什么是代理？
• ✅ 何时使用代理 / ⛔ 何时避免使用代理
• 代码代理
• 介绍 smolagents：让代理变得简单 🥳
• 建立代理
• 开放模型对于代理工作流程有多强大？
• 下一步

🤔 什么是代理？

任何使用人工智能的有效系统都需要为 LLM 提供某种形式的现实世界访问权限：例如，调用搜索工具获取外部信息，或执行某些程序以解决任务的可能性。换句话说，LLM 应该具有代理权。代理程序是 LLM 通往外部世界的门户。

AI 代理是 LLM 输出控制工作流程的程序。

任何利用 LLM 的系统都会将 LLM 输出集成到代码中。LLM 的输入对代码工作流程的影响是系统中 LLM 的代理级别。

请注意，根据此定义，“代理”不是一个离散的、0 或 1 的定义：相反，“代理”会在连续的范围内发展，因为您在工作流程中为 LLM 赋予或多或少的权力。

下表说明了代理在不同系统之间的差异：

机构级别	描述	怎么称呼	示例模式
☆☆☆	LLM 输出对程序流程没有影响	简单处理器	process_llm_output(llm_response)
★☆☆	LLM 输出决定基本控制流	路由器	if llm_decision(): path_a() else: path_b()
★★☆	LLM 输出决定函数执行	工具调用	run_function(llm_chosen_tool, llm_chosen_args)
★★★	LLM 输出控制迭代和程序延续	多步代理	while llm_should_continue(): execute_next_step()
★★★	一个代理工作流可以启动另一个代理工作流	多代理	if llm_trigger(): execute_agent()

多步骤代理具有以下代码结构：

memory = [user_defined_task]
while llm_should_continue(memory): # this loop is the multi-step partaction = llm_get_next_action(memory) # this is the tool-calling partobservations = execute_action(action)memory += [action, observations]

因此，该系统循环运行，在每个步骤执行新操作（该操作可能涉及调用一些预先确定的工具，这些工具只是函数），直到其观察结果表明已达到令人满意的状态以解决给定的任务。

✅ 何时使用代理 / ⛔ 何时避免使用代理

当你需要 LLM 来确定应用程序的工作流程时，代理很有用。但它们往往是多余的。问题是：我真的需要工作流程中的灵活性来有效地解决手头的任务吗？如果预先确定的工作流程经常失败，这意味着你需要更多的灵活性。

例如，假设你正在制作一个处理冲浪旅行网站上客户请求的应用程序。你可以提前知道请求将属于两个存储桶中的任一个（基于用户选择），并且你为这两个情况中的每一个都有一个预定义的工作流程。

• 想要了解一些旅行知识？⇒ 让他们访问搜索栏来搜索你的知识库
• 想与销售人员谈谈？⇒ 让他们输入联系表格。

如果确定性工作流程适合所有查询，那么就一定要编写所有内容！这将为您提供一个 100% 可靠的系统，并且不会因让不可预测的 LLM 干扰您的工作流程而引入错误的风险。为了简单和稳健，建议规范化为不使用任何代理行为。

但如果无法提前确定工作流程该怎么办？

例如，用户想要问：“I can come on Monday, but I forgot my passport so risk being delayed to Wednesday, is it possible to take me and my stuff to surf on Tuesday morning, with a cancellation insurance?” 这个问题取决于许多因素，并且上述预定的标准可能都不能满足这个请求。

如果预先确定的工作流程经常出现不足，则意味着您需要更大的灵活性。这正是代理设置能提供帮助的地方。

在上面的例子中，您可以创建一个多步骤代理，该代理可以访问天气 API 来获取天气预报、Google Maps API 来计算旅行距离、员工可用性仪表板以及知识库中的 RAG 系统。

直到最近，计算机程序还局限于预先确定的工作流程，试图通过堆积 if/else 开关来处理复杂性。它们专注于极其狭窄的任务，例如“计算这些数字的总和”或“在此图中查找最短路径”。但实际上，大多数现实生活中的任务，比如我们上面的旅行示例，并不适合预先确定的工作流程。代理系统为程序打开了广阔的现实世界任务世界！

代码代理

在多步骤代理中，LLM 可以在每一步中以调用外部工具的形式编写操作。编写这些操作的常见格式（由 Anthropic、OpenAI 和许多其他公司使用）通常是“将操作编写为包含工具名称和要使用的参数的 JSON，然后对其进行解析以了解要执行哪个工具以及使用哪些参数”的不同版本。

多篇研究论文表明，使用代码调用 LLM 的工具效果要好得多。

原因很简单，我们精心设计了代码语言，以便以最佳方式表达计算机执行的操作。如果 JSON 代码片段是一种更好的表达方式，那么 JSON 将成为顶级编程语言，而编程将成为人间地狱。

下图取自《可执行代码操作引出更好的 LLM 代理》，说明了用代码编写操作的一些优点：

用代码而不是类似 JSON 的代码片段来编写操作可以提供更好的效果：

• 可组合性：您是否可以将 JSON 操作嵌套在一起，或者定义一组 JSON 操作以供以后重复使用，就像定义一个 Python 函数一样？
• 对象管理：如何 generate_image 以 JSON 格式存储操作的输出？
• 通用性：代码是为了简单表达计算机可以做的任何事情而构建的。
• LLM 训练数据中的表示：LLM 的训练数据中已经包含大量高质量的代码操作，这意味着它们已经接受过这方面的训练！

介绍 smolagents：让代理变得简单 🥳

我们的建设 smolagents 目标是：

• ✨简单：代理逻辑只需几千行代码（参见此文件）。我们将抽象保持在原始代码之上的最小形状！
• 🧑‍💻一流支持代码代理，即以代码编写其操作的代理（而不是“用于编写代码的代理”）。为了确保安全，我们支持通过 E2B 在沙盒环境中执行。
• 🤗 Hub 集成：您可以与 Hub 共享工具并加载工具，未来还将有更多功能！
• 🌐支持任何 LLM：它支持在其版本中或通过我们的推理 API 加载的 Hub 上托管的模型 transformers，但也通过我们的 LiteLLM 集成支持来自 OpenAI、Anthropic 和许多其他的模型。

smolagents 是 transformers.agents 的后继者，并将在 transformers.agents 将来被弃用时替代它。

建立代理

要构建代理，至少需要两个元素：

• tools：代理有权访问的列表
• model：LLM 将成为您的代理人的引擎。

对于 model，您可以使用任何 LLM，要么使用 HfApiModel 上面豹子示例中显示的类打开模型，利用 Hugging Face 的免费推理 API，要么利用 LiteLLMModel litellm 从 100 多个不同的 LLM 列表中进行选择。

对于该工具，您可以创建一个函数，在输入和输出上使用类型提示，并使用文档字符串为输入提供描述，然后使用 @tool 装饰器使其成为一个工具。

下面介绍了如何制作一个自定义工具来获取 Google 地图的旅行时间，并将其用于旅行计划代理：

from typing import Optional
from smolagents import CodeAgent, HfApiModel, tool@tool
def get_travel_duration(start_location: str, destination_location: str, departure_time: Optional[int] = None) -> str:"""Gets the travel time in car between two places.Args:start_location: the place from which you start your ridedestination_location: the place of arrivaldeparture_time: the departure time, provide only a `datetime.datetime` if you want to specify this"""import googlemaps # All imports are placed within the function, to allow for sharing to Hub.import osgmaps = googlemaps.Client(os.getenv("GMAPS_API_KEY"))if departure_time is None:from datetime import datetimemonday = datetime(2025, 1, 6, 11, 0)directions_result = gmaps.directions(start_location,destination_location,mode="transit",departure_time=departure_time)return directions_result[0]["legs"][0]["duration"]["text"]agent = CodeAgent(tools=[get_travel_duration], model=HfApiModel(), additional_authorized_imports=["datetime"])agent.run("Can you give me a nice one-day trip around Paris with a few locations and the times? Could be in the city or outside, but should fit in one day. I'm travelling only via public transportation.")

经过收集旅行时间和运行计算的几个步骤后，代理返回了最终建议：

Out - Final answer: Here's a suggested one-day itinerary for Paris:
Visit Eiffel Tower at 9:00 AM - 10:30 AM
Visit Louvre Museum at 11:00 AM - 12:30 PM
Visit Notre-Dame Cathedral at 1:00 PM - 2:30 PM
Visit Palace of Versailles at 3:30 PM - 5:00 PM
Note: The travel time to the Palace of Versailles is approximately 59
minutes from Notre-Dame Cathedral, so be sure to plan your day accordingly.

构建工具后，将其分享到 Hub 非常简单：

get_travel_duration.push_to_hub("{your_username}/get-travel-duration-tool")

您可以在此空间下看到结果。您可以在空间中的文件 tool.py 下检查该工具的逻辑。如您所见，该工具实际上被导出到从 class 继承的类 Tool，这是我们所有工具的底层结构。

开放模型对于代理工作流程有多强大？

我们 CodeAgent 用一些领先的模型创建了实例，并在这个基准上对它们进行了比较，该基准收集了来自几个不同基准的问题，以提出各种各样的挑战。

在此处找到基准，了解所使用的代理设置的更多详细信息，并查看代码代理与工具调用代理的比较（剧透：代码效果更好）。

通过这一比较可以看出，开源模型现在可以与最好的封闭模型相媲美了！

下一步

• 从导游开始，熟悉图书馆。
• 学习更深入的教程以了解更多有关工具或一般最佳实践的知识。
• 深入研究示例来设置特定系统：文本到 SQL、代理 RAG 或多代理编排。
• 了解有关代理的更多信息：
  • Anthropic 的这篇精彩博客文章提供了扎实的常识。
  • 本合集汇集了有关代理商的最具影响力的研究论文。

# 参考资料- https://huggingface.co/blog/smolagents