Hugging Face 小型代理：用 50 行代码构建基于 MCP 的代理

Hugging Face 已经展示，借助模型上下文协议（MCP）以及现代大语言模型的原生工具调用支持，功能性 AI 代理可以在大约 50 行代码中实现。核心认识是，一旦建立了用于处理工具发现和执行的 MCP 客户端，代理本质上只是一个在 LLM 推理和工具执行之间交替的 while 循环。

模型上下文协议（MCP）作为工具标准

MCP 充当一种标准 API，用于公开可与 LLM 集成的一组工具。通过使用 MCP，开发者可以将工具与 LLM 实现解耦，使推理客户端能够将来自不同 MCP 服务器的可用工具挂接到模型的推理流程中。

目前，MCP 服务器以本地进程的形式运行。Hugging Face 的实现使用 @modelcontextprotocol/sdk/client TypeScript SDK 连接这些服务器，并通过 listTools() 方法获取可用工具。这些工具随后被重新格式化为 JSONSchema 表示（名称、描述和参数），以兼容原生 LLM 工具调用接口。

使用 InferenceClient 实现 MCP 客户端

为了构建基于 MCP 的代理，Hugging Face 使用 @huggingface/inference JS 库中的 InferenceClient。该架构由三个主要组件组成：

  1. Inference Client: 管理与 LLM 提供商（例如 Nebius）以及模型（例如 Qwen2.5-72B-Instruct）的连接。
  2. MCP Client Sessions: 为每个已连接的 MCP 服务器维护会话映射，以处理工具执行。
  3. Tool Registry: 从所有已连接的 MCP 服务器聚合的可用工具列表。

当 LLM 生成工具调用时，客户端会识别对应的 MCP 会话，并使用 client.callTool() 方法执行函数并获取结果，然后将其作为工具消息反馈给 LLM。

代理架构：“While 循环”逻辑

代理被定义为系统提示、LLM 推理客户端、MCP 客户端以及基本控制流的组合。Hugging Face 避免手动将工具描述注入提示，而是依赖推理引擎的原生 tools 参数。

控制流与循环终止

代理的主循环在工具调用和将结果反馈给 LLM 之间迭代。循环在以下条件下终止：

  • Explicit Task Completion: LLM 调用特定的 task_complete 工具以明确完成任务。
  • User Interaction: LLM 调用 ask_question 工具以请求用户提供更多信息。
  • Turn Limit: 回合数超过预定义的 MAX_NUM_TURNS。
  • Response Pattern: 当 LLM 连续两条非工具消息时，循环终止。

实际应用与演示

用户可以通过 npx @huggingface/mcp-client 运行完整演示。默认配置会连接两个本地 MCP 服务器：

  • File System Server: 允许代理访问本地桌面，以读取和写入文件。
  • Playwright MCP Server: 提供一个沙盒化的 Chromium 浏览器，用于网页导航和搜索。

例如，代理可以处理复杂的多步骤提示，如将一首俳句写入桌面上的文件，或对推理提供商执行 Brave 搜索并打开前三个结果。

技术规格与可扩展性

  • Default Model: Qwen/Qwen2.5-72B-Instruct
  • Default Provider: Nebius
  • Language: TypeScript/JavaScript（使用 async generators 处理 LLM 响应）。
  • Extensibility: 该系统设计为可与任何兼容 OpenAI 的客户端 SDK 以及包括 Cerebras、Cohere、Fireworks 等在内的各种推理提供商一起使用。它还支持通过 llama.cpp 或 LM Studio 使用本地 LLM。

Sources