Hugging Face hf CLI のエージェント最適化設計により、トークン使用量を削減し成功率を向上

Hugging Face hf CLI のエージェント最適化設計により、トークン使用量を削減し成功率を向上

TL;DR

Hugging Faceは、hf CLI がエージェント向けに再設計されたことを発表しました。これにより、Claude Code や Codex のようなコーディングエージェントがマルチステップの Hub タスクを実行する際、トークン使用量を最大 6分の1 に削減し、成功率を向上させることが可能になります。

Hub におけるエージェントのトラフィック

Hugging Face は 2026 年 4 月から、Hub におけるコーディングエージェントの使用状況の追跡を開始しました。CLAUDECODE、CODEX_SANDBOX、および汎用的な AI_AGENT のような環境変数を検出することで、hf CLI はリクエストに agent/<name> ユーザーエージェントヘッダーを付与します。最もアクティブな 2 つのエージェントは、Claude Code (約 39.5k のユニークユーザー、48.6M リクエスト) と Codex (約 34.8k ユーザー、36.4M リクエスト) です。2026 年 4 月以降に収集されたこれらの数値だけでも、エージェントが Hub トラフィックの大部分を占め、増加傾向にあることを示しています。

人間とエージェントの両方向けに設計

CLI は、検出されたエージェント環境に基づいて自動的に選択される 2 つの出力モードをサポートしています。

1 つのコマンド、複数のレンダリング

  • Human mode (インタラクティブなターミナルでのデフォルト) は、整列されたテーブルを表示し、長いフィールドを切り詰め、ANSI カラーを追加し、役立つヒントを表示します。
  • Agent mode (自動検出) は、ANSI コードや切り詰めなしで、完全な識別子、ISO タイムスタンプ、完全なタグリストを含む生の TSV を出力します。この形式はトークンベースの LLM にとってコンパクトで、解析が容易です。

両方のモードは同じ基盤となるロギングヘルパー (.table(), .result(), .json()) を共有しており、--format human|agent|json|quiet で強制的に指定することもできます。

次のコマンドへのヒント

すべての成功したコマンドは、ユーザーまたはエージェントが実行すべき正確な次の CLI 呼び出し（ID を含む）を示す決定論的なヒントで終了するようになりました。エラーにも、Use --yes to skip confirmation. のような実行可能な提案が含まれます。ヒントは stderr に出力されるため、エージェントが解析するデータストリームを汚染することはありません。

ノンブロッキングかつ再試行可能

  • エージェントモードでは、破壊的なコマンドはインタラクティブな確認を求める代わりに、明確な修正メッセージとともに即座に失敗します。
  • --exist-ok や --dry-run のような冪等なフラグにより、繰り返し実行が安全になります。これは、タイムアウト時に自動的に再試行するエージェントにとって不可欠です。

発見しやすく、予測可能なコマンド

CLI は一貫した resource + verb パターン (hf models ls, hf repos create, hf jobs run) に従っています。各 --help セクションはコピー＆ペースト可能な例で終了しており、エージェントがコマンドを素早く一致させることを可能にします。-q (1 行に 1 ID) や --json のようなオプションにより、パイプ処理やダウンストリーム処理がさらに簡素化されます。

コーディングエージェント向けの hf CLI ベンチマーク

専用のテスト環境を使用して、2 つのエージェント（Claude Code (Sonnet 4.6) と Codex (GPT-5.5)）にわたる 18 の現実的な Hub タスク（例：トレンドモデルの集計、ブランチ/タグ付きリポジトリの作成、バケットの同期）を評価しました。各タスクは、以下のいずれかで実行されました：

  1. hf CLI (機能あり/なし)
  2. 直接の curl 呼び出し / huggingface_hub Python SDK

各構成はタスクごとに 10 回の繰り返しを実行し、合計約 1,000 回の評価済み実行が行われました。成功は、エージェントの TASK_COMPLETE マーカーを信頼するのではなく、ライブの Hub に再クエリすることで検証されました。

結果の要約

エージェント ツール 成功スコア CLI に対するトークン使用量 自己申告エラー
Claude Code (Sonnet 4.6) hf CLI 0.94 baseline 2 / 163
curl / SDK 0.84 1.3–1.6× 11 / 163
Codex (GPT-5.5) hf CLI 0.93 baseline 3 / 163
curl / SDK 0.92 1.6–1.8× 10 / 163

複雑なマルチステップタスク (例：バケットの同期 + 削除、ブランチ/タグ付きのリポジトリ作成) では、curl/SDK を使用するとトークン数が 2.4 倍から 6 倍 に増加しましたが、単純な読み取り専用操作では、curl/SDK とほぼ同等か、あるいは curl/SDK の方がわずかに有利な結果となりました。

主な教訓

  • hf CLI は、マルチステップのワークフローにおいて一貫して高い成功率と劇的に低いトークン消費量を達成しています。
  • より強力な LLM (GPT-5.5) を使用していても、curl/SDK は非効率なままです。また、より弱いモデル (Sonnet 4.6) では、多くの書き込み操作の完了に失敗します。

hf-CLI スキル

Hugging Face は、すべてのコマンドのシグネチャ、1 行の説明、および必須フラグをリストした自動生成された skill を提供しています。エージェントは以下の方法でこのスキルをロードできます：

hf skills add            # ほとんどのエージェント用
hf skills add --claude   # Claude 固有のエントリを含む

エージェントがコマンドを見つけるために --help を調査する必要がなくなるため、タスクあたりの平均ツール呼び出し回数は約 10 回から約 7 回（約 30% 削減）に減少します。スキルは固定のコンテキスト・スライスを追加するだけなので、トークン使用量はほぼ一定に保たれます。

自分で試してみる

  1. CLI をインストールする:
# macOS / Linux
curl -LsSf https://hf.co/cli/install.sh | bash
# Windows (PowerShell)
powershell -ExecutionPolicy ByPass -c "irm https://hf.co/cli/install.ps1 | iex"
  1. エージェント用のスキルを追加する:
hf skills add            # 汎用エージェント用
hf skills add --claude   # Claude Code 用
  1. 認証 (hf auth login) を行い、エージェントに次のようなプロンプトを与える:
Use `hf` to list my Hugging Face Hub models, datasets, and Spaces.
Take a look at how I am currently using the Hub and suggest a few ways you could help me.

エージェントは適切な hf コマンドを生成し、最小限のトークンオーバーヘッドで実行します。

新しいエージェント・ハーネスの登録

新しいコーディングエージェントのハーネスを開発した場合は、小さな PR を通じて agent-harnesses.ts にその検出エントリを追加してください。これにより、CLI がエージェントを認識し、トラフィックにタグを付け、エージェント最適化された出力モードを適用できるようになります。

参照: 完全なベンチマークのトランスクリプトは https://huggingface.co/buckets/celinah/hf-cli-agent-benchmark で入手可能です。完全なコマンドリファレンスは hf CLI ガイド にあります。

Sources