このガイドでは、エージェントを構築し、実行し、そしてユースケースに合わせて動作するようにエージェントをカスタマイズする方法を学習します。
smolagents は 2 つのエージェント・クラスを備えています : CodeAgent と ToolCallingAgent で、これらはエージェントがツールとやりとるする方法について 2 つの異なるパラダイムを表しています。

smolagents : Get Started : エージェント – 案内ツアー

作成 : クラスキャット・セールスインフォメーション
作成日時 : 08/22/2025
バージョン : v1.21.1

* 本記事は github.com/huggingface/smolagents の以下のページを独自に翻訳した上で、補足説明を加えてまとめ直しています :

Get started : Agents – Guided tour

* サンプルコードの動作確認はしておりますが、必要な場合には適宜、追加改変しています。
* ご自由にリンクを張って頂いてかまいませんが、sales-info@classcat.com までご一報いただけると嬉しいです。

smolagents : Get Started : エージェント – 案内ツアー

このガイドでは、エージェントを構築し、実行し、そしてユースケースに合わせて動作するようにエージェントをカスタマイズする方法を学習します。

エージェントの種類の選択 : CodeAgent または ToolCallingAgent

smolagents は 2 つのエージェント・クラスを備えています : CodeAgent と ToolCallingAgent で、これらはエージェントがツールとやりとるする方法について 2 つの異なるパラダイムを表しています。主な違いはアクションが指定され実行される方法にあります : コード生成 vs 構造化ツール呼び出しです。

CodeAgent は Python コードスニペットとしてツール呼び出しを生成します。
- コードはローカル (安全でない可能性があります) または安全なサンドボックス内で実行されます。
- ツールは Python 関数として (バインディング経由で) 公開されます。
- ツール呼び出しの例 :
```
result = search_docs("What is the capital of France?")
print(result)
```
- 強み :
  - 高い表現力: 複雑なロジックと制御フローを可能にし、ツール、ループ、変換、推論を組み合わせることができます。
  - 柔軟性: すべての可能性のあるアクションを事前定義する必要はなく、新しいアクション/ツールを動的に生成できます。
  - 創発的推論 (Emergent reasoning) : 他段階問題や動的ロジックに最適です。
- 制限事項 :
  - エラーのリスク: 構文エラーや例外を処理する必要があります。
  - 予測可能性が低い : 予期せぬ出力や安全でない出力の可能性が高まります。
  - 安全な実行環境を必要とします。
ToolCallingAgent はツール呼び出しを構造化 JSON として記述します。
- これは多くのフレームワーク (OpenAI API) で使用される一般的な形式で、コード実行なしに構造化ツール相互作用を可能にします。
- ツールは JSON スキーマで定義されます: 名前、説明、パラメータ型等。
- ツール呼び出しの例 :
```
{
  "tool_call": {
    "name": "search_docs",
    "arguments": {
      "query": "What is the capital of France?"
    }
  }
}
```
- 強み :
  - 信頼性 : ハルシネーションの可能性が低く、出力は構造化され検証されます。
  - 安全性 : 引数は厳密に検証され、任意のコードが実行されるリスクはありません。
  - 相互運用性 : 外部 API やサービスへのマッピングが容易です。
- 制限 :
  - 低い表現力 : 結果を動的に組み合わせたり変換したり、あるいは複雑なロジックや制御フローを実行することが容易ではありません。
  - 柔軟性がない : すべての可能なアクションを前もって定義する必要があり、定義済みツールに制限されます。
  - コード合成なし : ツール機能に制限されます。

どちらのエージェント型を使用するべきか :

CodeAgent は以下の場合に使用します :
- 推論、連鎖や動的構成が必要。
- ツールが組み合わせられる関数である (e.g., パース + 数学 + クエリ)。
- エージェントがソルバーやプログラマーである。
ToolCallingAgent は以下の場合に使用します :
- 単純でアトミックなツールを持つ (e.g., API を呼び出す、ドキュメントの取得)。
- 高い信頼性と明確な検証を望む。
- エージェントがディスパッチャーやコントローラのようなものである。

CodeAgent

CodeAgent は Python コード・スニペットを生成してアクションを実行しタスクを解決します。

デフォルトでは、Python コードの実行はローカル環境で行われます。これは安全なはずです、何故ならば、呼び出せる関数は提供されたツール (特に Hugging Face によるツールだけの場合) と、print や math モジュールからの関数のような定義済みの安全な関数のセットだけだからです、つまり実行できるものが既に制限されています。

Python インタープリタはまたデフォルトではセーフリスト外のインポートを許可しませんので、最も明白な攻撃のすべては問題とはならないはずです。CodeAgent の初期化時に、引数 additional_authorized_imports で承認されたモジュールを文字列のリストとして渡すことで追加のインポートを承認することができます :

model = InferenceClientModel()
agent = CodeAgent(tools=[], model=model, additional_authorized_imports=['requests', 'bs4'])
agent.run("Could you get me the title of the page at url 'https://huggingface.co/blog'?")

さらに、追加のセキュリティレイヤーとして、サブモジュールへのアクセスは、インポートリスト内で明示的に承認されていない限りは、デフォルトでは禁止されています。例えば、numpy.random サブモジュールにアクセスするには、additional_authorized_imports リストに ‘numpy.random’ を追加する必要があります。これはまた numpy.* を使用して承認することもできます、これは numpy に加えて numpy.random とそれ自体のサブパッケージのような、任意のサブパッケージを許容します。

The LLM can generate arbitrary code that will then be executed: do not add any unsafe imports!

不正な操作を実行しようとするコードで、あるいはエージェントにより生成されたコードにより通常の Python エラーがあれば、実行は停止します。

ローカルの Python インタープリタの代わりに、E2B コードエグゼキューターや Docker を使用することもできます。E2B の場合、まず E2B_API_KEY 環境変数を設定してから、エージェント初期化時に executor_type=”e2b” を渡します。Docker については、初期化時に executor_type=”docker” を渡します。

Note : Learn more about code execution in this tutorial.

ToolCallingAgent

ToolCallingAgent は、多くのフレームワーク (OpenAI API) で使用される一般的な形式である JSON ツール呼び出しを出力します、これはコード実行なしで構造化ツール相互作用を可能にします。

それは CodeAgent と殆ど同じように動作しますが、もちろんコードは実行しないので additional_authorized_imports はありません :

from smolagents import ToolCallingAgent

agent = ToolCallingAgent(tools=[], model=model)
agent.run("Could you get me the title of the page at url 'https://huggingface.co/blog'?")

エージェントの構築

最小限のエージェントを初期化するには、少なくともこれら 2 つの引数が必要です :

model, エージェントを強化するためのテキスト生成モデル。エージェントは単純な LLM とは異なり、LLM をエンジンとして使用するシステムです。以下のオプションのいずれかを使用できます :
- TransformersModel は事前に初期化された transformers パイプラインを取り、transformers を使用してローカルマシン上で推論を実行します。
- InferenceClientModel は、内部的には huggingface_hub.InferenceClient を利用し、ハブ上のすべての推論プロバイダーをサポートします : Cerebras, Cohere, Fal, Fireworks, HF-Inference, Hyperbolic, Nebius, Novita, Replicate, SambaNova, Together 等。
- LiteLLMModel は LiteLLM 経由で 100+ の様々なモデルとプロバイダーを呼び出すことができます。
tools, タスクを解決するためにエージェントが使用できる Tools のリスト。空のリストでも構いません。また、オプションの引数 add_base_tools=True を定義することで、ツールリストの最上位にデフォルトのツールボックスを追加できます。

これら 2 つの引数、tools と model を用意すれば、エージェントを作成して実行できます。Inference Providers, transformers, ollama, LiteLLM, Azure OpenAI, Amazon Bedrock, or mlx-lm のいずれか経由で、好きな LLM を使用できます。

OpenAI or Anthropic API

LiteLLMModel を使用するには、環境変数 ANTHROPIC_API_KEY or OPENAI_API_KEY を設定するか、初期化時に api_key 変数を渡す必要があります。

# !pip install smolagents[litellm]
from smolagents import CodeAgent, LiteLLMModel

model = LiteLLMModel(model_id="anthropic/claude-3-5-sonnet-latest", api_key="YOUR_ANTHROPIC_API_KEY") # Could use 'gpt-4o'
agent = CodeAgent(tools=[], model=model, add_base_tools=True)

agent.run(
    "Could you give me the 118th number in the Fibonacci sequence?",
)

エージェント実行の調査

実行後に何が起こったか調べるのに有用な幾つかの属性があります :

agent.logs はエージェントのきめ細かいログを保存します。エージェントの実行のステップ毎に、すべてが辞書に保存され、agent.logs に追加されます。
agent.write_memory_to_messages() の実行はエージェントのメモリをチャットメッセージのリストとして書き出し、モデルが表示できるようにします。このメソッドはログの各ステップを調べ、関心のあるものだけをメッセージとして保存します : 例えば、システムプロンプトとタスクは別々のメッセージに保存し、各ステップについては LLM 出力をメッセージとして、ツール呼び出し出力を別のメッセージとして保存します。何が起きたかの高位レベルなビューを望む場合に使用します – しかしすべてのログがこのメソッドにより転記されるわけではありません。

ツール

ツールはエージェントにより使用されるアトミック関数です。LLM により使用されるためには、API を構成する幾つかの属性も必要で、このツールを呼び出す方法を LLM に説明するために使用されます :

名前
説明
入力型と説明
出力型

例えば PythonInterpreterTool を確認できます、それは名前、説明、入力説明、出力型、そしてアクションを実行するための forward メソッドを持ちます。

エージェントが初期化される際、ツール属性が使用されてツール説明が生成されます、これはエージェントのシステムプロンプトに組み込まれます。これは、エージェントにどのツールを何故使用するかを知らせることができます。

デフォルト・ツールボックス

smolagents を “toolkit” エクストラ付きで smolagents をインストールすれば、エージェントを強化するデフォルトのツールボックスを備えます、それは初期化時に引数 add_base_tools=True によりエージェントに追加することができます :

DuckDuckGo web 検索* : DuckDuckGo ブラウザを使用して web 検索を実行します。
Python コード・インタープリタ : LLM が生成した Python コードを安全な環境で実行します。コードベースのエージェントは Python コードをネイティブに実行できるので、このツールは、add_base_tools=True で初期化した場合にのみ ToolCallingAgent に追加されます。
Transcriber : Whisper-Turbo 上に構築された、音声をテキストに変換する、音声-to-テキスト・パイプラインです。

ツールを引数とともに呼び出すことで、手動で使用できます。

# !pip install smolagents[toolkit]
from smolagents import WebSearchTool

search_tool = WebSearchTool()
print(search_tool("Who's the current president of Russia?"))

新しいツールの作成

Hugging Face のデフォルトツールによりカバーされないユースケースに対して、独自のツールを作成することができます。例えば、ハブから、指定されたタスクについて最もダウンロードされたモデルを返すツールを作成しましょう。

以下のコードで始めましょう。

from huggingface_hub import list_models

task = "text-classification"

most_downloaded_model = next(iter(list_models(filter=task, sort="downloads", direction=-1)))
print(most_downloaded_model.id)

このコードは、関数にラップしてツール・デコレータを追加するだけで、素早くツールに変換できます : これがツールを構築する唯一の方法ではありません : それを Tool のサブクラスとして直接定義することもできます、これは、例えば思いクラス属性を初期化する可能性など、より柔軟性を与えます。

Let’s see how it works for both options:

@tool で関数をデコレートする

from smolagents import tool

@tool
def model_download_tool(task: str) -> str:
    """
    This is a tool that returns the most downloaded model of a given task on the Hugging Face Hub.
    It returns the name of the checkpoint.

    Args:
        task: The task for which to get the download count.
    """
    most_downloaded_model = next(iter(list_models(filter=task, sort="downloads", direction=-1)))
    return most_downloaded_model.id

Tool のサブクラス化

from smolagents import Tool

class ModelDownloadTool(Tool):
    name = "model_download_tool"
    description = "This is a tool that returns the most downloaded model of a given task on the Hugging Face Hub. It returns the name of the checkpoint."
    inputs = {"task": {"type": "string", "description": "The task for which to get the download count."}}
    output_type = "string"

    def forward(self, task: str) -> str:
        most_downloaded_model = next(iter(list_models(filter=task, sort="downloads", direction=-1)))
        return most_downloaded_model.id

Note : Read more on tools in the dedicated tutorial.

マルチエージェント

マルチエージェント・システムは Microsoft のフレームワーク Autogen により導入されました。

このタイプのフレームワークでは、タスクを解決するために一つのエージェントの代わりに、連携する複数のエージェントを持ちます。それは経験的に、殆どのベンチマークでより良いパフォーマンスを発揮します。この優れたパフォーマンスの理由は概念的には単純です : 多くのタスクについて、do-it-all (何でも屋) システムを使用するよりも、サブタスクにユニットを特化させるほうが好ましいからです。ここでは、エージェントに個別のツールセットとメモリを持たせることが効率的な専門化を実現できます。例えば、web 検索エージェントによりアクセスした web ページのコンテンツすべてを、コード生成エージェントのメモリに何故収めるのでしょう？それらは分離させておくほうが良いです。

smolagents を使用して、階層型マルチエージェント・システムを簡単に構築できます。

そのためには、エージェントが name と description 属性を持つことを確実にするだけです、これらは (ツールに対して行うのと同様に) マネージャ・エージェントのシステムプロンプトに埋め込まれ、この管理されるエージェントを呼び出す方法を知らせることができます。それから、マネージャ・エージェントの初期化時に、パラメータ managed_agents で管理されるエージェントを渡すことができます。

ネイティブ WebSearchTool を使用する特定の web 検索エージェントを管理するエージェントを作成する例が以下です :

from smolagents import CodeAgent, InferenceClientModel, WebSearchTool

model = InferenceClientModel()

web_agent = CodeAgent(
    tools=[WebSearchTool()],
    model=model,
    name="web_search_agent",
    description="Runs web searches for you. Give it your query as an argument."
)

manager_agent = CodeAgent(
    tools=[], model=model, managed_agents=[web_agent]
)

manager_agent.run("Who is the CEO of Hugging Face?")

Note : For an in-depth example of an efficient multi-agent implementation, see how we pushed our multi-agent system to the top of the GAIA leaderboard.

エージェントと会話し、その思考をクールな Gradio インターフェイスで視覚化する

GradioUI を使用して、エージェントに対話的にタスクを送信し、その思考と実行プロセスを観察することができます、以下が例です :

from smolagents import (
    load_tool,
    CodeAgent,
    InferenceClientModel,
    GradioUI
)

# Import tool from Hub
image_generation_tool = load_tool("m-ric/text-to-image", trust_remote_code=True)

model = InferenceClientModel(model_id=model_id)

# Initialize the agent with the image generation tool
agent = CodeAgent(tools=[image_generation_tool], model=model)

GradioUI(agent).launch()

以上

月	火	水	木	金	土	日
				1	2	3
4	5	6	7	8	9	10
11	12	13	14	15	16	17
18	19	20	21	22	23	24
25	26	27	28	29	30	31