AIエージェント入門

smolagentsとは何か？Pythonで作るAIエージェント入門

19分で読める
smolagentsとは何か？Pythonで作るAIエージェント入門

この記事の結論

Hugging FaceのsmolagentsでAIエージェントを構築する実践ガイド。CodeAgent・ToolCallingAgent・MCP連携・マルチエージェントをコード例つきで解説。

「AIエージェントを作りたいんだけど、LangChainは重すぎて…もっと手軽に始められないの？」

最近、こういう声をよく聞くようになりました。実際、LangChainやLangGraphは強力ですが、初めて触る人には設定項目が多すぎて、最初の一歩がなかなか踏み出せない。そんな状況に対する、Hugging Faceからの回答が smolagents（スモールエージェンツ）です。

smolagentsは「シンプルさ」を哲学の中心に置いたPythonライブラリで、コア部分のコードはわずか約1,000行。それでいてCodeAgent、ToolCallingAgent、MCPサーバー連携、マルチエージェント構成まで、本番レベルの機能が揃っています。この記事では、インストールから実践的なユースケースまでを、コピペ可能なコード例つきで解説します。

そもそもsmolagentsとは何か

smolagentsは、Hugging Faceが2024年末にリリースしたオープンソースのAIエージェントフレームワークです。現在の最新バージョンは v1.24.0（2026年1月16日リリース）。GitHubスターは急増中で、シンプルさと実用性のバランスで支持を集めています。

最大の特徴は「コードエージェント（CodeAgent）」というコンセプトです。多くのフレームワークはエージェントの行動をJSONで表現しますが、smolagentsのCodeAgentはPythonコードそのものを生成・実行します。これにより、ループ、条件分岐、関数の組み合わせといった複雑な処理を自然に表現できます。

他のフレームワークとの比較

フレームワーク コア行数 アクション形式 学習コスト MCP対応
smolagents 約1,000行 Pythonコード / JSON 低 あり
LangChain 数万行 JSON 高 あり（拡張）
LangGraph 数千行 グラフ+JSON 中〜高 あり（拡張）
Pydantic AI 数千行 型安全JSON 中 あり
CrewAI 数千行 JSON 中 あり

最終確認日: 2026-03-17

smolagentsの「コア約1,000行」という数字は、フレームワークの透明性とデバッグのしやすさに直結します。何か問題が起きたとき、ソースコードを読んで理解できる規模感です。これは大規模フレームワークにはない強みです。

AIエージェントの基本的な設計パターンについては、AIエージェント導入5フェーズガイドで体系的に解説しています。smolagentsを使い始める前に全体像を把握しておくと理解が深まります。

何が新しいのか — CodeAgentというアプローチ

smolagentsを理解するうえで最も重要なのが、CodeAgentとToolCallingAgentの違いです。

CodeAgent：Pythonコードでツールを呼ぶ

CodeAgentは、LLMにPythonコードスニペットを生成させ、そのコードを実行します。例えば「東京の天気を調べて、摂氏を華氏に変換してから返して」というタスクを与えると、こんなコードを生成します：

weather = search_tool("東京の現在の天気 気温")
celsius = float(weather.split("°C")[0].split()[-1])
fahrenheit = celsius * 9/5 + 32
final_answer(f"東京の気温は {celsius}°C（{fahrenheit:.1f}°F）です")

ループも条件分岐も自由自在。複数のツールを組み合わせた複雑な処理を、コードという表現力豊かな言語で書けるのが特徴です。

ToolCallingAgent：JSONで構造的に呼ぶ

一方、ToolCallingAgentはOpenAI APIの標準的なtool callingと同じJSON形式を使います：

{
  "tool_call": {
    "name": "search_tool",
    "arguments": {
      "query": "東京の現在の天気 気温"
    }
  }
}

JSONなので出力が構造化されており、検証しやすく、外部APIとの連携がシンプルです。ただし複数ツールを動的に組み合わせる表現力はCodeAgentに劣ります。

どちらを選ぶか

判断基準 CodeAgent ToolCallingAgent
複雑なロジック（ループ・条件分岐）が必要 ◎ △
ツールを動的に組み合わせたい ◎ △
出力の予測可能性・安全性が重要 △ ◎
シンプルなAPIコール・単発ツール実行 △ ◎
本番環境でのセキュアな実行 E2B/Docker推奨 そのまま使える

正直なところ、ほとんどのユースケースではCodeAgentの方が表現力が高くて便利です。ただし、本番環境でユーザー入力を処理する場合は、コードのサンドボックス実行（E2BやDockerを使う）を検討してください。

具体的に何ができるようになるのか

ここからが本番です。実際に動くコード例を3パターン紹介します。

即効テクニック1：5分でセットアップ——基本のCodeAgent

まずはインストールから。toolkit extrasを含めると、DuckDuckGo検索などのデフォルトツールが使えます：

pip install 'smolagents[toolkit]'

# Claude/GPTを使う場合はlitellmも
pip install 'smolagents[toolkit,litellm]'

次に、最もシンプルなエージェントを作ってみましょう。Hugging Faceのモデルを無料で使う場合：

# 注意: 本番環境で使用する前に、必ずテスト環境で動作確認してください。

import os
from smolagents import CodeAgent, InferenceClientModel, DuckDuckGoSearchTool

# HF_TOKEN環境変数を設定（無料アカウントで利用可能）
# os.environ["HF_TOKEN"] = "hf_..."

model = InferenceClientModel(
    model_id="Qwen/Qwen2.5-Coder-32B-Instruct"
)

agent = CodeAgent(
    tools=[DuckDuckGoSearchTool()],
    model=model,
    max_steps=5  # 無限ループ防止
)

result = agent.run("2026年3月に発表された最新のAIエージェントフレームワークを3つ教えてください")
print(result)

動作環境: Python 3.10+, smolagents 1.24.0

ClaudeやGPT-4oを使いたい場合はLiteLLMモデルを使います：

# 注意: 本番環境で使用する前に、必ずテスト環境で動作確認してください。

from smolagents import CodeAgent, LiteLLMModel, DuckDuckGoSearchTool

model = LiteLLMModel(
    model_id="anthropic/claude-sonnet-4-6",  # または "gpt-4o"
    # api_key="your-api-key"  # 環境変数 ANTHROPIC_API_KEY でも可
)

agent = CodeAgent(
    tools=[DuckDuckGoSearchTool()],
    model=model
)

result = agent.run("東京都の最新の補助金制度を調べて、AIスタートアップが使えるものをまとめてください")
print(result)

ポイント: LiteLLMのおかげで100以上のモデルに同じコードで接続できます。モデルの切り替えは model_id を変えるだけです。

即効テクニック2：カスタムツールを30行で作る

smolagentsのツール定義は驚くほどシンプルです。@toolデコレータを使うだけで、任意のPython関数をエージェントのツールにできます：

# 注意: 本番環境で使用する前に、必ずテスト環境で動作確認してください。

import requests
from smolagents import tool, CodeAgent, LiteLLMModel

@tool
def get_github_stars(repo: str) -> str:
    """
    GitHubリポジトリのスター数を取得します。

    Args:
        repo: リポジトリ名（例: "huggingface/smolagents"）

    Returns:
        スター数と最終更新日を含む文字列
    """
    url = f"https://api.github.com/repos/{repo}"
    response = requests.get(url)
    if response.status_code != 200:
        return f"リポジトリ {repo} が見つかりませんでした"
    data = response.json()
    stars = data.get("stargazers_count", 0)
    updated = data.get("updated_at", "不明")[:10]
    return f"{repo}: {stars:,}スター（最終更新: {updated}）"


model = LiteLLMModel(model_id="anthropic/claude-sonnet-4-6")
agent = CodeAgent(tools=[get_github_stars], model=model)

result = agent.run(
    "smolagents、LangChain、LangGraph、CrewAIのGitHubスター数を比較して、"
    "どれが最も人気かまとめてください"
)
print(result)

動作環境: Python 3.10+, smolagents 1.24.0, requests

ポイントは3つです。関数名がツール名になります。docstringがツールの説明としてLLMに渡されます（ここを丁寧に書くと精度が上がります）。Args:セクションの説明がパラメータの説明として使われます。

即効テクニック3：MCPサーバーと接続する

smolagentsはMCP（Model Context Protocol）に対応しており、既存のMCPサーバーのツールをそのまま使えます。例えば、HTTP接続のMCPサーバーをエージェントに接続するには：

# 注意: 本番環境で使用する前に、必ずテスト環境で動作確認してください。
# pip install 'smolagents[mcp]'

from smolagents import CodeAgent, LiteLLMModel, MCPClient

model = LiteLLMModel(model_id="anthropic/claude-sonnet-4-6")

# コンテキストマネージャで自動的に接続・切断を管理
with MCPClient(
    {"url": "http://127.0.0.1:8000/mcp", "transport": "streamable-http"}
) as mcp_tools:
    agent = CodeAgent(
        tools=mcp_tools,  # MCPサーバーのツールを直接渡す
        model=model,
        add_base_tools=True  # DuckDuckGo等のデフォルトツールも追加
    )
    result = agent.run("顧客データベースから先月の売上上位10社を抽出して")
    print(result)

stdioベース（コマンドラインで起動するタイプ）のMCPサーバーに接続する場合：

# 注意: 本番環境で使用する前に、必ずテスト環境で動作確認してください。

from mcp import StdioServerParameters
from smolagents import CodeAgent, LiteLLMModel, ToolCollection

# PubMed MCPサーバーの例
server_params = StdioServerParameters(
    command="uvx",
    args=["pubmedmcp@0.1.3"],
    env={"UV_PYTHON": "3.12", **os.environ}
)

with ToolCollection.from_mcp(
    server_params, trust_remote_code=True
) as tool_collection:
    agent = CodeAgent(
        tools=[*tool_collection.tools],
        model=LiteLLMModel(model_id="anthropic/claude-sonnet-4-6")
    )
    result = agent.run("AIエージェントに関する最新の研究論文を3本探して要約してください")
    print(result)

動作環境: Python 3.10+, smolagents[mcp] 1.24.0, mcp

MCPサーバーの詳細については、MCPガイドも参照してください。

よくある誤解

誤解1：「smolagentsは小規模用で、本番には向かない」

これはよくある誤解です。smolagentsは「smol（スモール）」という名前ですが、それはコアコードの行数が少ないという意味で、処理できるタスクが小さいという意味ではありません。

実際、Hugging Face自身がGAIAベンチマーク（汎用AIアシスタントの性能評価）でsmolagentsを使ったマルチエージェントシステムでトップスコアを達成しています。コアが小さいことで、むしろ理解しやすく、カスタマイズしやすいという利点があります。

誤解2：「CodeAgentはセキュリティリスクが高い」

確かに、任意コードを実行する仕組みなので、考慮は必要です。ただし、smolagentsはデフォルトでセキュアなサンドボックスを用意しています。

  • デフォルトでは安全なモジュール（math等）のみをimport許可
  • 明示的に許可したモジュール以外はimport不可
  • 本番環境には E2B、Docker、Blaxelのサンドボックス実行が利用可能
# セキュアなサンドボックス実行（E2B使用）
# pip install 'smolagents[e2b]'
# E2B_API_KEY 環境変数を設定

agent = CodeAgent(
    tools=[DuckDuckGoSearchTool()],
    model=model,
    executor_type="e2b"  # E2Bクラウドサンドボックスで実行
)

ユーザー入力を直接エージェントに渡す場合は、必ずサンドボックスを使いましょう。内部業務での自動化用途であれば、デフォルト設定でも十分なケースが多いです。

誤解3：「Hugging Faceモデルしか使えない」

これも誤解です。前述のとおり、LiteLLMを使えばOpenAI、Anthropic、Google Gemini、Mistral、ローカルOllamaなど100以上のモデルプロバイダーに対応します。AzureOpenAIやAmazon Bedrockにも直接接続できます。

マルチエージェント構成を組んでみる

smolagentsのマルチエージェントは、エージェント自体をツールとして扱うシンプルな設計です。「マネージャーエージェント」が「ワーカーエージェント」を呼び出します：

# 注意: 本番環境で使用する前に、必ずテスト環境で動作確認してください。

from smolagents import CodeAgent, LiteLLMModel, WebSearchTool, DuckDuckGoSearchTool

model = LiteLLMModel(model_id="anthropic/claude-sonnet-4-6")

# ワーカーエージェント1：ウェブ検索専門
web_research_agent = CodeAgent(
    tools=[WebSearchTool()],
    model=model,
    name="web_research_agent",
    description=(
        "ウェブ検索を実行します。最新情報の調査、ニュース収集、"
        "製品情報の確認などを依頼できます。クエリ文字列を引数として渡してください。"
    )
)

# ワーカーエージェント2：データ分析専門
@tool
def calculate_statistics(numbers_str: str) -> str:
    """
    数値リスト（カンマ区切り）の統計情報を計算します。
    平均、中央値、最大値、最小値を返します。

    Args:
        numbers_str: カンマ区切りの数値文字列（例: "10, 20, 30, 40"）
    """
    import statistics
    numbers = [float(n.strip()) for n in numbers_str.split(",")]
    return (
        f"平均: {statistics.mean(numbers):.2f}, "
        f"中央値: {statistics.median(numbers):.2f}, "
        f"最大: {max(numbers)}, 最小: {min(numbers)}"
    )

analysis_agent = CodeAgent(
    tools=[calculate_statistics],
    model=model,
    name="analysis_agent",
    description=(
        "数値データの統計分析を行います。"
        "数値のリストを渡すと、平均・中央値・最大・最小を計算します。"
    )
)

# マネージャーエージェント：両ワーカーを管理
manager = CodeAgent(
    tools=[],
    model=model,
    managed_agents=[web_research_agent, analysis_agent]
)

result = manager.run(
    "主要なAIエージェントフレームワーク（smolagents、LangChain、CrewAI）の"
    "GitHubスター数を調べて、数値を比較してください"
)
print(result)

動作環境: Python 3.10+, smolagents 1.24.0

設計のポイントとして、nameとdescriptionをしっかり書くことが重要です。マネージャーエージェントは、この説明をもとにどのワーカーに何を依頼するかを判断します。曖昧な説明だと、適切なワーカーが選ばれません。

【要注意】よくある失敗パターンと回避策

失敗1：ツールのdocstringが雑すぎる

❌ よくある間違い：

@tool
def search(q: str) -> str:
    """Search."""
    ...

⭕ 正しいアプローチ：

@tool
def search_product_database(product_name: str) -> str:
    """
    社内製品データベースから製品情報を検索します。
    在庫数、価格、仕入先情報が返ります。

    Args:
        product_name: 検索する製品名（部分一致対応）
    """
    ...

なぜ重要か: LLMはdocstringを読んでツールの使い方を理解します。説明が不十分だと、ツールが正しく使われません。ツールの品質の50%はdocstringで決まります。

失敗2：max_stepsを設定しない

❌ よくある間違い：

agent = CodeAgent(tools=tools, model=model)
# デフォルトのmax_stepsのまま複雑なタスクを実行

⭕ 正しいアプローチ：

agent = CodeAgent(
    tools=tools,
    model=model,
    max_steps=10  # タスクの複雑さに応じて設定
)

なぜ重要か: max_stepsを適切に設定しないと、エージェントが無限ループに近い状態でAPIを呼び続け、予期しないコストが発生します。複雑なタスクには多めに、単純なタスクは少なめに設定しましょう。

失敗3：本番でCodeAgentをサンドボックスなしで使う

❌ よくある間違い：

# ユーザー入力をそのままエージェントに渡す
agent = CodeAgent(tools=tools, model=model)
agent.run(user_input)  # プロンプトインジェクションリスク

⭕ 正しいアプローチ：

# E2Bサンドボックスを使って安全に実行
agent = CodeAgent(
    tools=tools,
    model=model,
    executor_type="e2b"  # または "docker"
)
agent.run(user_input)

なぜ重要か: CodeAgentが生成したコードはPythonとして実行されます。悪意のあるユーザーが「このコードを実行して」のようなプロンプトを入力すると、意図しない操作が発生する可能性があります。

失敗4：Gradio UIで会話継続の設定を忘れる

❌ よくある間違い：デフォルトでは毎回の会話でメモリがリセットされる

⭕ 正しいアプローチ：

# 会話を継続するにはreset=Falseを明示
# agent.run(next_task, reset=False) で続きを実行
from smolagents import GradioUI
GradioUI(agent).launch()

なぜ重要か: デフォルトではrun()を呼ぶたびに記憶がリセットされます。チャットUIで前の会話を引き継ぎたい場合はreset=Falseフラグが必要です。

結局どうすればいいのか

smolagentsは「まず動かしてみて、必要に応じて拡張する」というアプローチに最も向いているフレームワークです。

今日から始める3つのアクション：

  1. 今日: pip install 'smolagents[toolkit]'してDuckDuckGoSearchToolでCodeAgentを動かしてみる。実際に動く姿を見ることが最速の理解方法です。
  2. 今週中: 自分の業務に関連するカスタムツールを1つ作り、エージェントに渡してみる。APIを叩くツール、社内DBを検索するツール、何でも良いです。
  3. 今月中: 本番ユースケースが見えてきたらサンドボックス（E2B/Docker）を設定し、マルチエージェント構成で複数の専門エージェントを組み合わせてみる。

正直なところ、smolagentsがすべてのユースケースに最適というわけではありません。複雑な状態管理が必要なワークフローにはLangGraph、型安全性を重視するならPydantic AI、マーケティング・セールスの自動化にはCrewAIが向いているケースもあります。ただし「まず試してみる」ためのフレームワークとして、smolagentsはいまのところ最も敷居が低い選択肢のひとつです。

フレームワーク選定で迷っている方は、AIエージェントフレームワーク比較2026も参考にしてください。各フレームワークの強み・弱みを整理しています。

参考・出典

この記事はAIgent Lab編集部がお届けしました。

AIエージェントを自社の業務に導入したい方、社内向けAI研修を検討中の方は、Uravation（運営会社）のお問い合わせフォームからお気軽にご相談ください。100社以上のAI導入支援実績があります。

Need help moving from reading to rollout?

この記事を読んで導入イメージが固まってきた方へ

Uravationでは、AIエージェントの要件整理、PoC設計、社内導入、研修まで一気通貫で支援しています。

30分無料相談を予約 支援実績を見る

この記事をシェア

X Facebook LINE

※ 本記事の情報は2026年3月時点のものです。サービスの料金・仕様は変更される可能性があります。最新情報は各サービスの公式サイトをご確認ください。

関連記事

AIエージェント入門

Gemini 3.1 Flash Live APIガイド｜リアルタイム音声AI実装

Gemini Flash Liveのリアルタイム音声・映像APIをPythonで...

22分で読める
AIエージェント入門

KAIROS・BUDDY・ULTRAPLAN開発者ガイド｜Claude Code未公開機能

Claude Codeリークで判明したKAIROS（常時稼働）・BUDDY（ペア...

26分で読める
Grok Build完全ガイド【2026年最新】8並列AIエージェントの使い方 AIエージェント入門

Grok Build完全ガイド【2026年最新】8並列AIエージェントの使い方

xAIのGrok Buildを徹底解説。8並列エージェント起動・Arena Mo...

12分で読める