【Hugging Face】超軽量AIエージェント開発フレームワーク「smolagents」入門！Pythonでの独自ツール実装とローカルLLM連携

はじめに：なぜ今「smolagents」なのか？

LLM（大規模言語モデル）の進化に伴い、自律的にタスクを遂行する「AIエージェント」の開発が活発化しています。しかし、従来のフレームワークの多くは、機能が肥大化してブラックボックス化しやすかったり、プロンプトの調整や複雑なJSONの解釈（Tool Calling）に過度のトークンを消費したりするという課題を抱えていました。

こうした課題に対するHugging Faceからの回答が、超軽量AIエージェント開発フレームワーク「smolagents」です。

smolagentsは、わずか約1,000行足らずのコアコードで書かれた非常にシンプルなライブラリでありながら、従来のフレームワークを凌駕する強力な機能を持っています。本記事では、smolagentsの設計思想である「コードファースト」の強みを紐解き、Pythonでのオリジナルツールの実装方法や、ローカルLLM（Ollama）と連携させたプライベートエージェントの構築手順まで詳しく解説します。

詳細な仕様や最新のアップデート情報については、Hugging Faceのsmolagents公式GitHubや、Hugging Faceの公式ドキュメントも合わせてご参照ください。

---

smolagentsの核心：「コードファースト（Code-Agent）」設計

従来の多くのAIエージェント（LangChainやLlamaIndex、Difyなど）は、LLMが次の行動を選択する際、JSONやXMLといった構造化データを出力し、それをシステム側がパースして関数を実行する「JSONベースのTool Calling」を採用しています。

これに対し、smolagentsの最大の特徴は「CodeAgent（Code-first Agent）」にあります。これは、LLMにテキストとして直接「Pythonの実行コードそのもの」を書かせ、それをセキュアなPythonインタプリタで逐次実行するアプローチです。

コードファーストが優れている理由

1. 表現力の圧倒的な高さ 「ツールAの実行結果がXだったらツールBを実行し、そうでなければツールCを3回ループする」といった複雑な条件分岐やループ処理を、JSONで表現するのは非常に困難です。Pythonコードであれば、数行の if 文や for ループで直感的に記述できます。
2. トークンの節約と精度の向上 複雑なタスクを1回1回JSONでやり取りするマルチターン対話に比べ、コードとして一括出力させることで、LLMとの往復（ステップ数）が激減します。結果としてAPIコストが削減され、処理速度が大幅に向上します。
3. 直感的なデバッグ LLMが出力したコードがそのまま実行ログに残るため、開発者は「エージェントが何を実行しようとしてエラーになったのか」を容易に把握できます。

---

環境構築と最初の「CodeAgent」の起動

まずは基本的な環境構築を行い、実際にsmolagentsを動かしてみましょう。

1. インストール

まずは必要なパッケージをインストールします。ここでは、smolagents本体と、LLM呼び出しを抽象化するLiteLLMなどの関連パッケージを導入します。

pip install smolagents litellm huggingface_hub

2. Hugging Face HubのAPIトークン設定

デフォルトでは、Hugging Faceが提供する推論API（Serverless Inference API）経由で、Qwenなどの強力なオープンモデルを使用できます。事前にHugging Faceのアカウントを作成し、APIトークンを取得して環境変数に設定しておきます。

export HF_TOKEN="your_huggingface_token_here"

3. 最初のエージェントコードの実行

以下のスクリプトは、Webから情報を検索するデフォルトツール（DuckDuckGoSearchTool）を装備したエージェントを作成し、質問を投げかけるシンプルな例です。

from smolagents import CodeAgent, HfApiEngine, DuckDuckGoSearchTool

# LLMエンジンの初期化（Hugging Faceの無料推論APIを使用）
engine = HfApiEngine(model_id="meta-llama/Llama-3.3-70B-Instruct")

# エージェントの初期化（Web検索ツールを付与）
agent = CodeAgent(
    tools=[DuckDuckGoSearchTool()],
    model=engine
)

# タスクの実行
response = agent.run("最新のsmolagentsというライブラリについて、どのような特徴があるか調べて要約してください。")
print(response)

このコードを実行すると、LLMは自動的に DuckDuckGoSearchTool を使用するPythonスクリプトを脳内で生成し、それを実行して結果を統合し、日本語で要約を返してくれます。

---

Pythonでの独自ツール（Custom Tools）の実装

実務でAIエージェントを活用する際、最も重要になるのが「自社のAPIやデータベースと連携するカスタムツールの実装」です。smolagentsでは、Pythonの関数にデコレータを付与するだけで、非常に簡単にツールを作成できます。

@toolデコレータを使用した実装例

以下の例では、指定された都市の「現在時刻」を取得するカスタムツールを作成し、エージェントに組み込んでいます。ツール関数の「Docstring（トリプルクォートによる説明文）」と「型ヒント」は、LLMがツールの役割や使い方を理解するための重要なプロンプト情報として自動的に抽出されるため、必ず詳細に記述してください。

from datetime import datetime
import pytz
from smolagents import CodeAgent, HfApiEngine, tool

@tool
def get_current_time(timezone: str) -> str:
    """
    指定されたタイムゾーンの現在時刻を返すツールです。
    
    Args:
        timezone: タイムゾーン名（例：'Asia/Tokyo', 'America/New_York'）
        
    Returns:
        YYYY-MM-DD HH:MM:SS 形式の現在時刻文字列
    """
    try:
        tz = pytz.timezone(timezone)
        now = datetime.now(tz)
        return now.strftime("%Y-%m-%d %H:%M:%S")
    except Exception as e:
        return f"エラー: タイムゾーン '{timezone}' が見つかりません。({str(e)})"

# LLMエンジンとエージェントの作成
engine = HfApiEngine(model_id="meta-llama/Llama-3.3-70B-Instruct")
agent = CodeAgent(tools=[get_current_time], model=engine)

# カスタムツールを呼び出すタスクの実行
result = agent.run("東京とニューヨークの現在の時刻を調べて、その時差を計算してください。")
print(result)

コードの解説

• @tool デコレータを関数に付与することで、smolagents標準の Tool クラスに変換されます。
• 引数 timezone: str の型ヒントと、Docstring内の Args: および Returns: の記述を元に、smolagentsがLLM用のシステムプロンプトを自動生成します。
• LLMは「東京」と「ニューヨーク」それぞれの現在時刻を get_current_time('Asia/Tokyo') と get_current_time('America/New_York') を実行するPythonコードを出力して取得し、最終的な時差の計算まで自律して完結させます。

このように、高度なWeb操作が必要な自動化エージェントを構築したい場合は、browser-useによるWeb自動化の解説を組み合わせて、エージェント用のツールを拡張していくアプローチも非常に有効です。

---

ローカルLLM（Ollama）との連携方法

企業の機密データや個人情報を扱う場合、外部の商用APIにデータを送信できないケースがあります。smolagentsは、ローカルLLM実行環境である「Ollama」や「LiteLLM」と簡単に連携させることが可能です。

Ollamaのセットアップや基本的な動作環境については、Ollamaを用いたローカルAI開発環境構築の記事で詳しく解説しています。ここでは、Ollamaで事前に「Qwen2.5-Coder」または「Llama3」などのモデルが起動している前提で進めます。

Ollama / LiteLLM連携の実装手順

smolagentsでローカルLLMを動かすには、LiteLLMEngine を利用します。内部的にLiteLLMがOllamaのローカルサーバー（通常は http://localhost:11434）へリクエストを仲介します。

from smolagents import CodeAgent, LiteLLMEngine, tool

# ローカルで起動しているOllamaのモデルを指定
# 事前にローカル環境で「ollama run qwen2.5-coder:7b」を実行しておく必要があります
local_engine = LiteLLMEngine(
    model_id="ollama_chat/qwen2.5-coder:7b",
    api_base="http://localhost:11434"  # OllamaのデフォルトURL
)

@tool
def calculate_discount(price: float, discount_rate: float) -> float:
    """
    商品の元の価格と割引率から、割引後の価格を計算するツールです。
    
    Args:
        price: 元の価格（円）
        discount_rate: 割引率（0.0から1.0の間、例：20%引きなら0.2）
    """
    return price * (1.0 - discount_rate)

# ローカルLLMエンジンを搭載したエージェントの作成
local_agent = CodeAgent(
    tools=[calculate_discount],
    model=local_engine
)

# タスクの実行
response = local_agent.run("定価12,800円のジャケットが35%オフで販売されています。割引後の価格はいくらになりますか？")
print(response)

注意点とモデルの選定

ローカルLLMで CodeAgent を運用する場合、モデルには「高いコード生成能力」が求められます。Qwen2.5-Coderシリーズ（特に 7B-Instruct や 14B-Instruct、スペックに余裕があれば 32B-Instruct）は、コードファーストのエージェントをローカルで駆動させるのに現在最も適した選択肢の一つです。

---

トラブルシューティング：よくあるエラーと解決策

smolagentsを開発・運用する中で、特に遭遇しやすいエラーと、その原因および解決策をまとめました。

1. 「ImportError: HfApiEngine requires huggingface_hub...」または認証エラー

• 原因: huggingface_hub パッケージが不足しているか、環境変数 HF_TOKEN が正しくロードされていません。
• 解決策:

  pip install huggingface_hub
  

  を実行した上で、Pythonスクリプトの実行前にトークンが設定されていることを確認してください。Pythonコード内で直接設定する場合は、以下の記述を最上部に追加します。

  import os
  os.environ["HF_TOKEN"] = "your_actual_token_here"
  

2. 「Exception: Security error: sandbox...」などのコード実行エラー

• 原因: smolagentsは、LLMが作成した任意のPythonコードを実行するため、デフォルトでサンドボックス環境や安全なインタプリタを介してコードを制限しています。システムに危害を加えるようなライブラリ（例: subprocess や不審なファイル操作）をLLMが実行しようとすると、セキュリティブロックが発動します。
• 解決策: 基本的にはLLMへの不要なシステムライブラリ使用を避けるプロンプトを与えるか、どうしても特定のPython標準モジュールを追加でインポートさせたい場合は、CodeAgent インスタンスの引数 additional_authorized_imports に許可するモジュール名のリストを明示的に渡してください。

  agent = CodeAgent(
      tools=[...],
      model=engine,
      additional_authorized_imports=["math", "json", "numpy"]
  )
  

3. LLMが自作ツールを認識せず、独自のPython関数をその場で自作してしまう

• 原因: 関数のDocstringや型ヒントが不十分、あるいはLLMの性能（特に軽量なローカルLLMなど）が低いため、システムプロンプトの「利用可能なツール一覧」の指示を無視してしまっています。
• 解決策:
  1. 関数のDocstringをより明瞭で詳細な表記に修正する。
  2. LLMエンジンにQwen2.5-Coderなどのコード特化型モデルを採用する。
  3. エージェント作成時の system_prompt を上書きし、ツール利用のルールをより強調する。

---

まとめ

Hugging Faceの「smolagents」は、AIエージェントの処理の大部分を「Pythonコードの実行」に一元化することで、トークンの節約、圧倒的な表現力の獲得、そして軽量さを実現した極めてモダンなフレームワークです。

• 無料のHugging Face推論APIを使えば、数行で最高峰のオープンモデルによるエージェントを試せる
• @tool デコレータによるカスタムツール開発が極めてシンプル
• OllamaなどのローカルLLM環境と接続し、完全なプライベートAIエージェントをローカルPC上で構築可能

これから本格的なAIエージェントアプリやワークフロー自動化スクリプトを作成したいと考えている開発者の方は、ぜひこの軽量で強力な「smolagents」を第一の選択肢として検討してみてはいかがでしょうか。