Smolagents

<a href="https://github.com/huggingface/smolagents/blob/main/LICENSE"><img alt="ライセンス" src="https://img.shields.io/github/license/huggingface/smolagents.svg?color=blue"></a>
<a href="https://huggingface.co/docs/smolagents"><img alt="ドキュメント" src="https://img.shields.io/website/http/huggingface.co/docs/smolagents/index.html.svg?down_color=red&down_message=offline&up_message=online"></a>
<a href="https://github.com/huggingface/smolagents/releases"><img alt="GitHub リリース" src="https://img.shields.io/github/release/huggingface/smolagents.svg"></a>
<a href="https://github.com/huggingface/smolagents/blob/main/CODE_OF_CONDUCT.md"><img alt="コントリビューター規約" src="https://img.shields.io/badge/Contributor%20Covenant-v2.0%20adopted-ff69b4.svg"></a>
<a href="https://deepwiki.com/huggingface/smolagents"><img src="https://deepwiki.com/badge.svg" alt="DeepWiki に質問"></a>

コードで考えるエージェント！

smolagents は、わずか数行のコードで強力なエージェントを実行できるライブラリです。次の特長があります。

✨ シンプルさ：エージェントのロジックは約1,000行のコードに収まっています（agents.pyを参照）。生のコードに近い、最小限の抽象化を採用しています！

🧑‍💻 コードエージェントを第一級でサポート。CodeAgentは、（「コードを書くためにエージェントを使う」のではなく）コードでアクションを記述します。安全性を確保するため、Blaxel、E2B、Modal、Dockerを使ったサンドボックス環境での実行をサポートしています。

🤗 Hub との統合：ツールやエージェントをHubと共有したり、Hubから取得したりして、最も効率的なエージェントをすぐに共有できます！

🌐 モデルに依存しない設計：smolagentsはあらゆるLLMをサポートしています。ローカルのtransformersモデルやollamaモデル、Hub上の多数のプロバイダー、またはLiteLLM統合を介したOpenAI、Anthropicなどのモデルを利用できます。

👁️ モダリティに依存しない設計：エージェントはテキスト、画像、動画、さらには音声の入力にも対応しています！画像についてはこちらのチュートリアルをご覧ください。

🛠️ ツールに依存しない設計：MCP サーバーやLangChainのツールを利用できるほか、Hub Spaceをツールとして使うこともできます。

詳しいドキュメントはこちらをご覧ください。

メモ

smolagentsについて詳しくは、公開ブログ記事をご覧ください！

クイックデモ

まず、標準のツールセットでパッケージをインストールします。

pip install "smolagents[toolkit]"

次にエージェントを定義し、必要なツールを与えて実行します！

from smolagents import CodeAgent, WebSearchTool, InferenceClientModel

model = InferenceClientModel()
agent = CodeAgent(tools=[WebSearchTool()], model=model, stream_outputs=True)

agent.run("How many seconds would it take for a leopard at full speed to run through Pont des Arts?")

https://github.com/user-attachments/assets/84b149b4-246c-40c9-a48d-ba013b08e600

エージェントを Space リポジトリとして Hub に共有することもできます。

agent.push_to_hub("m-ric/my_agent")

# agent.from_hub("m-ric/my_agent") to load an agent from Hub

このライブラリは LLM に依存しません。上記の例は、任意の推論プロバイダーに切り替えられます。

from smolagents import InferenceClientModel

model = InferenceClientModel(
    model_id="deepseek-ai/DeepSeek-R1",
    provider="together",
)

from smolagents import LiteLLMModel

model = LiteLLMModel(
    model_id="anthropic/claude-4-sonnet-latest",
    temperature=0.2,
    api_key=os.environ["ANTHROPIC_API_KEY"]
)

import os
from smolagents import OpenAIModel

model = OpenAIModel(
    model_id="deepseek-ai/DeepSeek-R1",
    api_base="https://api.together.xyz/v1/", # Leave this blank to query OpenAI servers.
    api_key=os.environ["TOGETHER_API_KEY"], # Switch to the API key for the server you're targeting.
)

import os
from smolagents import OpenAIModel

model = OpenAIModel(
    model_id="openai/gpt-4o",
    api_base="https://openrouter.ai/api/v1", # Leave this blank to query OpenAI servers.
    api_key=os.environ["OPENROUTER_API_KEY"], # Switch to the API key for the server you're targeting.
)

from smolagents import TransformersModel

model = TransformersModel(
    model_id="Qwen/Qwen3-Next-80B-A3B-Thinking",
    max_new_tokens=4096,
    device_map="auto"
)

import os
from smolagents import AzureOpenAIModel

model = AzureOpenAIModel(
    model_id = os.environ.get("AZURE_OPENAI_MODEL"),
    azure_endpoint=os.environ.get("AZURE_OPENAI_ENDPOINT"),
    api_key=os.environ.get("AZURE_OPENAI_API_KEY"),
    api_version=os.environ.get("OPENAI_API_VERSION")    
)

import os
from smolagents import AmazonBedrockModel

model = AmazonBedrockModel(
    model_id = os.environ.get("AMAZON_BEDROCK_MODEL_ID") 
)

CLI

smolagent と webagent の 2 つのコマンドを使って、CLI からエージェントを実行できます。

smolagent は、さまざまなツールを装備できる複数ステップの CodeAgent を実行するための汎用コマンドです。

# Run with direct prompt and options
smolagent "Plan a trip to Tokyo, Kyoto and Osaka between Mar 28 and Apr 7."  --model-type "InferenceClientModel" --model-id "Qwen/Qwen3-Next-80B-A3B-Thinking" --imports pandas numpy --tools web_search

# Run in interactive mode (launches setup wizard when no prompt provided)
smolagent

対話モードでは、次の項目を設定できます。

• エージェントの種類の選択（CodeAgent または ToolCallingAgent）
• 使用可能なツールボックスからのツール選択
• モデル設定（種類、ID、API 設定）
• 追加のインポートなどの詳細オプション
• タスクのプロンプト入力

一方、webagent は helium を使用する、ウェブ閲覧に特化したエージェントです（詳しくはこちらをご覧ください）。

たとえば、次のように実行します。

webagent "go to xyz.com/men, get to sale section, click the first clothing item you see. Get the product details, and the price, return them. note that I'm shopping from France" --model-type "LiteLLMModel" --model-id "gpt-5"

Code エージェントの仕組み

CodeAgent は、基本的に従来の ReAct エージェントと同じように動作します。ただし、LLM エンジンがアクションを Python コードスニペットとして記述する点が異なります。

flowchart TB
    Task[User Task]
    Memory[agent.memory]
    Generate[Generate from agent.model]
    Execute[Execute Code action - Tool calls are written as functions]
    Answer[Return the argument given to 'final_answer']

    Task -->|Add task to agent.memory| Memory

    subgraph ReAct[ReAct loop]
        Memory -->|Memory as chat messages| Generate
        Generate -->|Parse output to extract code action| Execute
        Execute -->|No call to 'final_answer' tool => Store execution logs in memory and keep running| Memory
    end
    
    Execute -->|Call to 'final_answer' tool| Answer

    %% Styling
    classDef default fill:#d4b702,stroke:#8b7701,color:#ffffff
    classDef io fill:#4a5568,stroke:#2d3748,color:#ffffff
    
    class Task,Answer io

アクションは Python コードスニペットになりました。そのため、ツール呼び出しは Python 関数呼び出しとして実行されます。たとえば、エージェントは次のように、1 つのアクションで複数のウェブサイトを検索できます。

requests_to_search = ["gulf of mexico america", "greenland denmark", "tariffs"]
for request in requests_to_search:
    print(f"Here are the search results for {request}:", web_search(request))

アクションをコードスニペットとして記述する方法は、LLM に呼び出したいツールの辞書を出力させるという現在の業界慣行よりも効果的であることが実証されています。ステップ数を 30% 削減し（つまり LLM の呼び出しも 30% 削減）、難易度の高いベンチマークでより高い性能を達成します。詳しくは、エージェントに関する概要ガイドをご覧ください。

コード実行には重大なセキュリティ上の懸念（任意コードの実行）があるため、エージェントのコードはサンドボックス内で実行してください。次の選択肢をサポートしています。

• E2B、Blaxel、Modal — セットアップが最も簡単な、マネージド型クラウドサンドボックス
• Docker — セルフホスト型のコンテナー分離

組み込みの LocalPythonExecutor はセキュリティサンドボックスではありません。いくつかの制限を適用しますが、回避される可能性があるため、セキュリティ境界として使用してはいけません。

CodeAgent に加えて、アクションを JSON／テキストの塊として記述する標準の ToolCallingAgent も提供しています。用途に最適なスタイルを選択できます。

このライブラリはどれくらいスモールですか？

抽象化を必要最小限に抑えることを目指しました。主要なコードである agents.py は、コードが 1,000 行未満です。 それでも、いくつかの種類のエージェントを実装しています。CodeAgent はアクションを Python コードスニペットとして記述し、より従来型の ToolCallingAgent は組み込みのツール呼び出しメソッドを活用します。また、マルチエージェントの階層構造、ツールコレクションからのインポート、リモートコード実行、ビジョンモデルなどもサポートしています。

ところで、そもそもなぜフレームワークを使うのでしょうか？それは、こうした処理の大部分が簡単ではないからです。たとえば、コードエージェントはシステムプロンプト、パーサー、実行処理の全体で、コード形式の一貫性を保つ必要があります。そこで、このフレームワークがその複雑さを処理します。もちろん、ソースコードを自由に改変し、必要な部分だけを使って、それ以外はすべて除外することもおすすめします！

エージェント型ワークフローにおいて、オープンモデルの性能はどれくらいですか？

最先端のモデルをいくつか使って CodeAgent のインスタンスを作成し、いくつかの異なるベンチマークから質問を集め、多様な課題を組み合わせたこちらのベンチマークで比較しました。

エージェントの構成の詳細については、ベンチマークコードはこちらをご覧ください。また、LLM のコードエージェントと通常の LLM を使った場合の比較もご確認ください（ネタバレ：コードエージェントのほうが優れています）。

この比較から、オープンソースモデルが最良のクローズドモデルに肩を並べるようになったことがわかります！

セキュリティ

コードを実行するエージェントを扱う際、セキュリティは極めて重要な考慮事項です。信頼できないコードから隔離できる、サンドボックス化された実行オプションを使用してください。

警告： LocalPythonExecutor が提供するのはベストエフォートの緩和策のみであり、セキュリティ境界ではありません。信頼できないコードの実行には使用しないでください。

セキュリティポリシー、脆弱性の報告、エージェントを安全に実行するための詳細については、セキュリティポリシーをご覧ください。

貢献する

どなたでも貢献できます。貢献ガイドを参考に、ぜひ始めてみてください。

smolagents の引用

出版物で smolagents を使用する場合は、次の BibTeX エントリを使って引用してください。

@Misc{smolagents,
  title =        {`smolagents`: a smol library to build great agentic systems.},
  author =       {Aymeric Roucher and Albert Villanova del Moral and Thomas Wolf and Leandro von Werra and Erik Kaunismäki},
  howpublished = {\url{https://github.com/huggingface/smolagents}},
  year =         {2025}
}