开始使用 Smolagents：15分钟构建你的第一个代码代理

📢 转载信息

原文链接：https://www.kdnuggets.com/getting-started-with-smolagents-build-your-first-code-agent-in-15-minutes

原文作者：Shittu Olumide

Image by Author

开始使用 Smolagents：15分钟构建你的第一个代码代理

构建一个AI天气代理，仅用40行Python代码，使用Hugging Face的smolagents库。学习创建工具、连接LLMs，以及运行自主任务。

引言

AI已从简单的与大型语言模型（LLMs）聊天，发展到赋予它们执行数字世界中操作的能力。这些通常被称为Python AI代理——由LLMs驱动的自主软件程序，它们可以感知环境、做出决策、使用外部工具（如API或代码执行），并完成特定目标，而无需持续的人工干预。

如果你一直想尝试构建自己的AI代理，但又被复杂的框架所困扰，那么你来对地方了。今天，我们将介绍smolagents，这是Hugging Face开发的一个强大而极其简单的库。

在本文结束时，你将理解smolagents的独特性，更重要的是，你将拥有一个可以从互联网获取实时数据的代码代理。让我们开始实现吧。

理解代码代理

在我们开始编码之前，先来理解一下这个概念。代理本质上是一个配备了工具的LLM。你给模型一个目标（例如“获取伦敦当前天气”），它会决定使用哪些工具来实现该目标。

smolagents库中Hugging Face代理的特别之处在于其推理方法。与许多生成JSON或文本来决定使用哪个工具的框架不同，smolagents代理是代码代理。这意味着它们会编写Python代码片段来链接它们的工具和逻辑。

这非常强大，因为代码是精确的。它是表达循环、条件和数据操作等复杂指令最自然的方式。LLM不必猜测如何组合工具，只需编写Python脚本即可完成。

作为一个开源代理框架，smolagents透明、轻量级，非常适合学习基础知识。

先决条件

为了跟上进度，你需要：

• Python知识。你应该熟悉变量、函数和pip安装。
• 一个Hugging Face token。由于我们将使用Hugging Face生态系统，所以我们会使用他们的免费推理API。你可以通过在huggingface.co注册并访问你的设置来获取token。
• 一个Google账户是可选的。如果你不想在本地安装任何东西，可以在Google Colab笔记本中运行此代码。

设置你的环境

让我们准备好我们的工作空间。打开你的终端或一个新的Colab笔记本，然后安装该库。

mkdir demo-project cd demo-project

接下来，让我们设置安全token。最好将其存储为环境变量。如果你正在使用Google Colab，可以使用左侧面板中的secrets标签添加HF_TOKEN，然后通过userdata.get('HF_TOKEN')访问它。

构建你的第一个代理：天气查询器

对于我们的第一个项目，我们将构建一个可以查询给定城市天气数据的代理。为此，代理需要一个工具。工具只是LLM可以调用的一个函数。我们将使用一个免费的公共API，名为wttr.in，它以JSON格式提供天气数据。

安装和设置

创建一个虚拟环境：

python -m venv env

虚拟环境会隔离项目的依赖项。现在，让我们激活虚拟环境。

Windows:

env\Scripts\activate

macOS/Linux:

source env/bin/activate

激活后，你会在终端看到(env)。

安装所需的包：

pip install smolagents requests python-dotenv

我们安装了smolagents，Hugging Face用于构建具有工具使用能力的AI代理的轻量级代理框架；requests，用于进行API调用的HTTP库；以及python-dotenv，它将从.env文件中加载环境变量。

就这样——仅用一个命令。这种简单性是smolagents理念的核心。

Figure 1: Installing smolagents

设置API Token

在项目根目录下创建一个.env文件，然后粘贴以下代码。请将占位符替换为你的实际token：

HF_TOKEN=your_huggingface_token_here

从huggingface.co/settings/tokens获取你的token。你的项目结构应该如下所示：

Figure 2: Project structure

导入库

打开你的demo.py文件并粘贴以下代码：

import requests import os from smolagents import tool, CodeAgent, InferenceClientModel

• requests: 用于向天气API发出HTTP请求
• os: 安全地读取环境变量
• smolagents: Hugging Face的轻量级代理框架，提供：
  • @tool: 一个装饰器，用于定义代理可调用的函数。
  • CodeAgent: 一个编写和执行Python代码的代理。
  • InferenceClientModel: 连接到Hugging Face托管的LLMs。

在smolagents中，定义一个工具非常简单。我们将创建一个函数，该函数以城市名称作为输入并返回天气状况。将以下代码添加到你的demo.py文件中：

@tool def get_weather(city: str) -> str: """ Returns the current weather forecast for a specified city. Args: city: The name of the city to get the weather for. """ # Using wttr.in which is a lovely free weather service response = requests.get(f"https://wttr.in/{city}?format=%C+%t") if response.status_code == 200: # The response is plain text like "Partly cloudy +15°C" return f"The weather in {city} is: {response.text.strip()}" else: return "Sorry, I couldn't fetch the weather data."

让我们分解一下：

• 我们从smolagents导入tool装饰器。此装饰器将我们普通的Python函数转换为代理可以理解和使用的工具。
• get_weather函数中的文档字符串（""" ... """）至关重要。代理读取此描述以了解工具的作用以及如何使用它。
• 函数内部，我们向wttr.in发出一个简单的HTTP请求，这是一个免费的天气服务，返回纯文本天气预报。
• 类型提示（city: str）告诉代理要提供什么输入。

这是工具调用工作的完美示例。我们正在为代理提供一项新功能。

配置LLM

hf_token = os.getenv("HF_TOKEN") if hf_token is None: raise ValueError("Please set the HF_TOKEN environment variable") model = InferenceClientModel( model_id="Qwen/Qwen2.5-Coder-32B-Instruct", token=hf_token )

代理需要一个大脑——一个能够推理任务的大型语言模型（LLM）。这里我们使用：

• Qwen2.5-Coder-32B-Instruct: 一个强大的、专注于代码的模型，托管在Hugging Face上。
• HF_TOKEN: 你的Hugging Face API token，为了安全起见存储在.env文件中。

现在，我们需要创建代理本身。

agent = CodeAgent( tools=[get_weather], model=model, add_base_tools=False )

CodeAgent是一个特殊的代理类型，它：

• 编写Python代码来解决问题。
• 在一个沙箱环境中执行该代码。
• 可以链接多个工具调用。

在这里，我们实例化一个CodeAgent。我们将一个包含get_weather工具和模型对象的列表传递给它。add_base_tools=False参数告诉它不包含任何默认工具，暂时保持我们的代理简单。

运行代理

这是激动人心的部分。让我们给代理一个任务。使用特定的提示运行代理：

response = agent.run( "Can you tell me the weather in Paris and also in Tokyo?" ) print(response)

当你调用agent.run()时，代理会：

1. 读取你的提示。
2. 推理它需要哪些工具。
3. 生成调用get_weather("Paris")和get_weather("Tokyo")的代码。
4. 执行代码并返回结果。

Figure 3: smolagents response

当你运行这段代码时，你将见证Hugging Face代理的魔力。代理接收你的请求，发现它有一个名为get_weather的工具，然后它在“脑海中”（使用LLM）编写一个小的Python脚本，看起来像这样：

这是代理的想法，不是你写的代码。

weather_paris = get_weather(city="Paris") weather_tokyo = get_weather(city="Tokyo") final_answer(f"Here is the weather: {weather_paris} and {weather_tokyo}")

Figure 4: smolagents final response

它执行这段代码，获取数据，并返回一个友好的答案。你刚刚构建了一个可以通过API浏览网络的代码代理。

幕后工作原理

Figure 5: The inner workings of an AI code agent

进一步扩展：添加更多工具

代理的能力随着工具集的增加而增长。如果我们想将天气报告保存到文件怎么办？我们可以创建另一个工具。

@tool def save_to_file(content: str, filename: str = "weather_report.txt") -> str: """ Saves the provided text content to a file. Args: content: The text content to save. filename: The name of the file to save to (default: weather_report.txt). """ with open(filename, "w") as f: f.write(content) return f"Content successfully saved to {filename}" # Re-initialize the agent with both tools agent = CodeAgent( tools=[get_weather, save_to_file], model=model, )

agent.run("Get the weather for London and save the report to a file called london_weather.txt")

现在，你的代理可以获取数据并与你的本地文件系统进行交互。这种技能的结合使得Python AI代理如此通用。

结论

在短短几分钟内，仅用不到20行的核心逻辑，你就构建了一个功能齐全的AI代理。我们已经看到了smolagents如何简化创建代码代理的过程，这些代理可以编写和执行Python来解决问题。

这个开源代理框架的美妙之处在于它消除了样板代码，让你能够专注于有趣的部分：构建工具和定义任务。你不再仅仅是与AI聊天，而是与一个能够采取行动的AI进行协作。这仅仅是开始。你现在可以探索让你的代理通过搜索API访问互联网，将其连接到数据库，或者让它控制一个网页浏览器。

参考和学习资源

• 官方文档：要了解所有功能，最好的地方是Hugging Face smolagents文档。
• 源代码：对于好奇的人来说，整个库都是开源的。你可以在Hugging Face smolagents GitHub仓库查看内部细节。
• 社区：查看Hugging Face论坛，了解其他人正在构建的内容。

Shittu Olumide是一位软件工程师和技术作家，热衷于利用尖端技术创作引人入胜的故事，他对细节一丝不苟，善于简化复杂概念。你也可以在Twitter上找到Shittu。

🚀 想要体验更好更全面的AI调用？

欢迎使用青云聚合API，约为官网价格的十分之一，支持300+全球最新模型，以及全球各种生图生视频模型，无需翻墙高速稳定，文档丰富，小白也可以简单操作。