Hugging Face Python 版 Tiny Agents

Hugging Face 将其 “Tiny Agents” 概念移植到 Python，扩展了 huggingface_hub 客户端 SDK，使其能够作为模型上下文协议（Model Context Protocol，MCP）客户端使用。通过标准化大型语言模型（LLM）发现和执行外部工具的方式，开发者只需约 70 行代码即可创建功能完整的 AI 代理。

模型上下文协议（MCP）

MCP 是一种开放协议，旨在标准化 LLM 与外部工具或 API 的交互。提供统一接口后，MCP 消除了开发者为每个工具编写自定义集成的需求，简化了向 LLM 添加新功能的过程。

运行与配置 Tiny Agents

在安装带有 mcp 额外依赖的 huggingface_hub 库后，即可通过 CLI 部署 Tiny Agents：

pip install "huggingface_hub[mcp]>=0.32.0"

代理配置

代理的行为由 agent.json 文件定义，可选的 PROMPT.md 用于提供详细的系统指令。agent.json 包含以下字段：

  • Model：要使用的 LLM（例如 Qwen/Qwen2.5-72B-Instruct）。
  • Provider：推理提供商（例如 Nebius）。
  • Servers：代理应连接的 MCP 服务器数组。这些服务器可以是 stdio（通过命令和参数本地运行的进程）或 http（远程工具）服务器。

部署示例

代理可以从本地配置加载，也可以直接从 Hugging Face Hub 上的 tiny-agents/tiny-agents 数据集加载。示例包括：

  • 网页浏览代理：使用 Playwright MCP 服务器操作沙箱 Chromium 浏览器。
  • 图像生成代理：连接到作为 MCP 服务器的 FLUX.1 [schnell] 图像生成 HF Space。

技术架构：MCPClient

huggingface_hub 中的 MCPClient 是管理工具使用功能的核心组件。其主要职责包括管理与 MCP 服务器的异步连接、发现可用工具、为 LLM 格式化工具信息以及执行工具调用。

连接与工具发现

add_mcp_server 方法根据服务器类型（stdio、sse 或 http）建立连接。连接后，客户端会初始化 ClientSession 并调用 list_tools() 获取服务器的可用工具。这些工具随后被格式化为兼容 OpenAI Chat Completions API 的模式，这是 InferenceClient 使用的标准接口。

工具执行循环

process_single_turn_with_tools 方法处理 LLM 交互循环：

  1. 准备：汇总来自 MCP 服务器的工具以及任何 “exit loop” 控制工具。
  2. 流式：使用 AsyncInferenceClient.chat.completions.create 对 LLM 发起流式调用。
  3. 处理：在块到达时，客户端重建文本响应并解析任何请求的工具调用。
  4. 执行：若调用了工具，客户端定位对应的 MCP 会话并通过 session.call_tool() 执行该工具。随后将结果格式化并加入对话历史。

代理实现

Agent 类继承自 MCPClient，并在其上添加了对话管理层。它被设计为一个简单循环，维护状态并判断任务何时完成。

初始化

创建时，Agent 使用系统提示初始化对话历史，并调用 load_tools() 连接所有配置的 MCP 服务器，填充代理的可用工具箱。

核心执行循环

Agent.run() 方法是一个异步生成器，通过 while True 循环处理用户输入。在每次迭代中，它将 LLM 与工具的交互委托给 process_single_turn_with_tools，并实时产出结果。

循环在以下三种条件下终止：

  • 明确调用了 “exit loop” 工具。
  • 达到最大回合数（MAX_NUM_TURNS）。
  • LLM 给出最终文本响应且不再需要工具调用。

Sources