Python における Hugging Face Tiny Agents

Hugging Face は「Tiny Agents」コンセプトを Python に移植し、huggingface_hub クライアント SDK を Model Context Protocol（MCP）クライアントとして機能させました。これにより、Large Language Models（LLM）が外部ツールを検出・実行する方法を標準化することで、約 70 行のコードで機能的な AI エージェントを作成できるようになります。

Model Context Protocol（MCP）

MCP は、LLM と外部ツールや API 間のやり取りを標準化することを目的としたオープンプロトコルです。汎用インターフェースを提供することで、開発者が個々のツールごとにカスタム統合を書く必要がなくなり、LLM に新しい機能を追加する作業が簡素化されます。

Tiny Agents の実行と設定

huggingface_hub ライブラリを mcp エクストラ付きでインストールした後、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 データセットから直接ロードできます。例としては次のようなものがあります。

  • Web ブラウジングエージェント: Playwright MCP サーバーを使用してサンドボックス化された Chromium ブラウザを操作します。
  • 画像生成エージェント: FLUX.1 [schnell] 画像生成 HF Space を MCP サーバーとして利用します。

技術アーキテクチャ: 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. Preparation: MCP サーバーからツールと「exit loop」制御ツールを集約します。
  2. Streaming: AsyncInferenceClient.chat.completions.create を用いて LLM へのストリーミング呼び出しを行います。
  3. Processing: チャンクが到着するたびにテキスト応答と要求されたツール呼び出しを再構築します。
  4. Execution: ツールが呼び出された場合、対応する MCP セッションを特定し、session.call_tool() でツールを実行します。結果は整形され、会話履歴に追加されます。

エージェント実装

Agent クラスは MCPClient を継承し、会話管理レイヤーを追加します。シンプルなループとして設計され、状態を保持しつつタスク完了のタイミングを判断します。

初期化

作成時に Agent はシステムプロンプトで会話履歴を初期化し、load_tools() を呼び出してすべての設定済み MCP サーバーに接続し、エージェントのツールボックスを構築します。

コア実行ループ

Agent.run() メソッドは非同期ジェネレータで、while True ループを通じてユーザー入力を処理します。各イテレーションで process_single_turn_with_tools に LLM とツールのやり取りを委譲し、結果をリアルタイムで yield します。

ループは次の 3 条件のいずれかで終了します。

  • 「exit loop」ツールが明示的に呼び出されたとき。
  • 最大ターン数（MAX_NUM_TURNS）に達したとき。
  • LLM が最終テキスト応答を返し、これ以上ツール呼び出しが不要なとき。

Sources