AIエージェントフレームワーク「smolagents」の使い方と選び方

AIエージェントフレームワークのsmolagentsは、Pythonでツールや計算処理を柔軟に組み合わせたい場合に向いています。利用する前提は、生成されたコードを制御された環境で実行できることです。Hugging Faceが提供するエージェントクラスは、CodeAgentとToolCallingAgentの2種類。次の行動をPythonで表すか、構造化されたツール呼び出しで表すかを選べます。シンプルな設計は、範囲を絞った問題解決に役立ちます。ただし、ワークフローの永続化、権限管理、実行環境の分離は、利用側で設計する必要があります。

2026年10月31日時点のHugging Face、LangChain、OpenAIの公式ドキュメントで確認しています。 以下では、処理の組み合わせ方、ワークフローの制御、実行環境の分離という観点から比較します。推奨する使い分けはアーキテクチャ上の判断であり、性能ベンチマークに基づくものではありません。

AIエージェントフレームワークのsmolagentsはPythonをどう使うか

smolagentsは、実行可能なコードを行動として使うエージェントを構築できる、Hugging FaceのオープンソースPythonライブラリです。 エージェントは、モデルが行動を選び、その結果を観察し、次に何をするかを決めるループとして動きます。CodeAgentは行動をPythonで表し、ToolCallingAgentは構造化されたツール呼び出しを使います。どちらにもモデルとツール群を渡します。Hugging Faceのエージェントリファレンス。

CodeAgentは、調査の途中で短いスクリプトを書けるリサーチャーだと考えるとわかりやすいでしょう。許可されたツールでレコードを取得し、返されたデータを加工して、答えを計算できます。使える機能と制約は開発者が定め、それらをつなぐ処理の一部をモデルが組み立てます。

レビュー用のコードファイルを成果物として出力するアシスタントとは、役割が異なります。ここで生成されるコードは、エージェントが次の行動を実行するための手段です。

比較するときは、アプリケーションのどの部分に柔軟性が必要なのかを考えると判断しやすくなります。

後半の2行は、LangGraphとOpenAI Agents SDKのドキュメントで重視されている設計を示しています。それぞれにしかできない機能という意味ではありません。フレームワークにどの部分の構造を担わせたいかが、選択の分かれ目です。

smolagentsのCodeAgent：処理の組み合わせをモデルに任せる

CodeAgentが力を発揮するのは、あらかじめ決めた呼び出しの一覧よりも、Pythonで表したほうが途中の処理を組み立てやすい場合です。 Hugging Faceは、ループ、条件分岐、複数ツールの組み合わせを強みとして挙げる一方、構文エラー、例外、想定外の動作への対処も必要だと説明しています。ガイドツアー。

たとえば、在庫レコードの不整合を調べる場面を考えてみます。読み取り専用の検索ツールで候補を取得したあと、エージェントは名称を正規化し、似た項目をまとめ、特定のフィールドを合計してから、どのレコードを追加で調べるか判断するかもしれません。こうした中間処理を記述するには、Pythonがよく合います。

実行結果は、モデルが次の判断を下すための材料になります。計算の失敗も、エージェントが対応を考えるための観察結果です。ただし、それを受けて必ず自力で修正できるわけではありません。

ToolCallingAgent：定義済みの操作に行動を絞る

操作の入出力や役割がすでに明確なら、ToolCallingAgentから始めるのが適しています。 Pythonの処理を生成する代わりに、ツール名と引数を含む構造化されたJSON呼び出しを出力します。Hugging Faceによる比較。

注文情報を調べ、規約を取得するサポートアシスタントなら、それだけで足りるかもしれません。手順が決まっているデータ変換は、通常のアプリケーションコードに任せればよいでしょう。明確な関数で表せるワークフローにPythonの自動生成を持ち込むと、見合う利点がないまま、失敗の原因を増やすことになります。

構造化された呼び出しでも、認可は必要です。注文のキャンセル要求が正しい形式になっていても、その顧客に対して実行してよい操作とは限りません。スキーマが伝えるのは「何が要求されたか」であり、「許可してよいか」を決めるのはアプリケーションです。

ツールとモデルは別々に選ぶ

ツールの範囲を絞り、モデルは独立して選びます。 この分離がsmolagentsの実用上の魅力です。業務機能をすべて定義し直さなくても、エージェントの推論を担うモデルを変更できます。

ツールは、使い方を明示した関数

smolagentsのツールは、関数に名前、説明、入力のメタデータ、出力の型を持たせたものです。型ヒントと適切なdocstringを備えたシンプルな関数なら、@toolデコレーターが向いています。より複雑なツールでは、Toolを継承してforwardに実行ロジックを記述します。ツールガイド。

在庫管理アシスタントに渡すなら、データベースへの無制限なアクセスよりも、「許可されたカタログ内のレコードを検索する」といった機能が適しています。テナントの確認、クエリの制限、応答量の上限は、ツールの実装内で処理します。どれほど説得力のあるプロンプトでも、こうしたチェックの代わりにはなりません。

モデルを使うアプリケーションにツールを公開する標準インターフェース、Model Context Protocol（MCP）からツールを取り込むこともできます。LangChainのツールやHugging Face Spaces向けのアダプターも利用できます。ただし、再利用できることと、実装を信頼できることは別です。Hubのツールは独自コードを実行するため、Hugging Faceは読み込み時にtrust_remote_code=Trueを明示的に指定するよう求めています。ツールの連携と読み込みに関するドキュメント。

この判断にはコードレビューが必要です。エージェントに提供する前に、ツールの実装と依存関係を確認してください。

モデルのバックエンドを選んでも、サンドボックスは決まらない

現在のモデルリファレンスでは、複数の接続方法が案内されています。

• **InferenceClientModel**は、Hugging Face Inference Providersを通じて接続します。
• **LiteLLMModel**は、LiteLLMのプロバイダー連携層を利用します。
• **TransformersModel**は、Transformersのモデルをローカルで実行します。
• **OpenAIModel**は、OpenAI互換のモデルサーバーに接続します。

ガイドツアーでは、ローカル推論向けにOllamaも紹介されています。これらはバックエンドの選択肢であり、どのモデルでもコード生成やツール選択を同じようにこなせるという保証ではありません。

「モデルをどこで動かすか」と「生成されたPythonをどこで動かすか」は、分けて考えます。ホスト型のモデルからDockerの実行環境を利用することもできますし、ローカルモデルでも危険な処理を生成する可能性はあります。推論を手元のマシンに移しただけでは、コードの実行環境は分離されません。

デモの段階を越えたら、再現性のためにモデルを明示的に設定してください。Hugging Faceは、InferenceClientModelのデフォルトモデルが変わる可能性を示しています。モデルの設定。

公式サンプルで実行の流れを確かめる

ツールを追加する前に、公式ドキュメントの計算タスクで実行の流れを確認します。 Hugging Faceの入門サンプルは、ツールを渡さずに1から10までの数の合計を求めるものです。以下では同じタスクを使い、サンドボックスガイドにあるDockerのコンテキストマネージャーの書き方を組み合わせています。元のサンプル、Docker実行環境の設定。

1. 1

   環境を準備する

   インストールガイドではPython 3.10以降が必要とされ、仮想環境の使用が推奨されています。このサンプルでは、Dockerもインストールして起動しておく必要があります。インストールガイド。

   python -m venv .venv
   source .venv/bin/activate
   pip install 'smolagents[docker]'

   Inference Providersの呼び出し権限を持つHugging Faceのトークンを、環境変数HF_TOKENに設定します。InferenceClientModelは、この変数を自動で読み取れます。トークンをスクリプトに書き込まないでください。認証の動作。

2. 2

   公式サンプルのタスクをDockerで実行する

   次のコードをsum_agent.pyとして保存します。

   from smolagents import CodeAgent, InferenceClientModel
   
   model = InferenceClientModel()
   
   with CodeAgent(
       tools=[],
       model=model,
       executor_type="docker",
   ) as agent:
       result = agent.run("Calculate the sum of numbers from 1 to 10")
       print(result)

   続いて実行します。

   python sum_agent.py

   ブロックを抜ける際、コンテキストマネージャーがサンドボックスの後片付けを行います。この例はドキュメントの内容を組み合わせたもので、本記事のために実行したテストの結果を示すものではありません。

3. 3

   計算結果と実行環境の境界を確認する

   数学的に期待される答えは55で、10 × 11 ÷ 2から求められます。生成するPythonはモデルが選ぶため、毎回まったく同じ実行ログや表現になるとは限りません。

   tools=[]は、独自のツールを渡していないという意味です。CodeAgentがPythonを実行できなくなるわけではありません。生成されたコードをDocker内で実行させるのは、実行環境の設定です。

このように手順が固定された計算なら、アプリケーションには通常のPythonコードを使うのが妥当です。このサンプルの目的は、エージェントの仕組みを把握することにあります。エージェントを導入するのは、途中の手順を選ぶこと自体が課題に含まれるときです。計算内容を英語で説明できるというだけでは、導入の理由になりません。

コードを実行するエージェントにはサンドボックスが必要

生成されたPythonは信頼できないコードとして扱い、信頼できない入力を受け付ける前に、明示的にサンドボックスを用意します。 デフォルトのローカル実行環境は、制限付きのインタープリターです。ホスト環境が隔離されることを保証するものではありません。Hugging Faceは、モデルの誤り、プロンプトインジェクション、攻撃を意図したリクエストをリスクとして挙げています。安全なコード実行。

ローカルインタープリターは、Pythonプログラムを構文解析した抽象構文木を、操作ごとに評価します。インポートとサブモジュールを制限し、操作数にも上限を設けています。こうした制御はリスクの軽減に役立ちますが、セキュリティガイドでは、ローカル実行にもリスクが残ると注意を促しています。追加のパッケージを許可すると、生成されたプログラムがアクセスできる範囲も広がります。

Hugging Faceが案内しているサンドボックスの選択肢

現在の実行環境APIは、ローカル実行に加えてBlaxel、E2B、Modal、Dockerをサポートしています。 以下の設定名は、CodeAgentリファレンスと実行環境のリファレンスに沿ったものです。

これらの設定とは別に、プロバイダーを選び、認証情報を用意します。インストールドキュメントにはオプションの依存関係が掲載されていますが、追加パッケージをインストールするだけでデプロイの設定が完了するわけではありません。

社内での実験なら、Dockerを使うことで、実行環境の分離を具体的に確認できます。信頼できないリクエストを処理するサービスでは、必要な隔離の水準、ライフサイクル、運用上の制御に合わせて環境を選びます。インフラ選びを広く検討したい場合は、AIエージェント向けコードサンドボックスの比較を参照してください。

コード片の隔離と、エージェント全体の隔離は異なる

エージェントを増やす前に、何をサンドボックス内に置くかを決めます。 Hugging Faceは、生成されたコード片だけをサンドボックスで実行する方法と、エージェントシステム全体をそこで動かす方法を区別しています。セキュリティガイドによると、コード片だけを隔離する方法は、別のエージェントから補助役として呼び出される「マネージドエージェント」に対応していません。システム全体を移す場合は追加の設定が必要になり、認証情報を渡す必要が生じることもあります。サンドボックスの構成方法。

これはアーキテクチャに関わる違いです。今後追加する専門エージェントが、実行環境の内側からモデルを呼び出す必要があるなら、当初の「コードを送り、結果を受け取る」という構成だけでは足りなくなるかもしれません。デプロイ構成を変更するときは、認証情報の置き場所とツールの依存関係を見直してください。

顧客向けサービスでは、エージェントを起動する前に、アクセスできるファイル、通信先、呼び出せる操作を定義します。各実行に与える権限は、そのタスクに必要な範囲に絞ってください。モデルが処理を終えられない場合も含め、タイムアウト、キャンセル、後片付けを通常の実行経路として設計します。

シンプルな設計が向いているのはどんなときか

アプリケーションで最も難しい制御上の課題を軸に、フレームワークを選びます。 初期化コードが短いのは便利ですが、その周囲に自分で書く必要があるコードのほうが重要です。

smolagentsとLangGraphの比較：動的な処理か、永続的なワークフロー制御か

明示的な業務状態に沿って処理を永続化し、一時停止してから再開する必要があるなら、LangGraphのほうが出発点として適しています。 LangGraphは、状態を持つワークフロー向けの低レベルなオーケストレーションランタイムで、永続化と人による介入をサポートしています。決定論的な処理とモデルが判断する処理を組み合わせることができ、LangChainは必須ではありません。LangGraphの概要。

根拠となる情報を集め、管理者の承認を待ち、承認後に再開する購買ワークフローを考えてみます。中心となる課題は、プロセスの状態を保持し、許可された状態遷移だけを実行することです。こうした要件がプロダクトの中心なら、LangGraphから検討するとよいでしょう。

その分、状態、遷移、永続化、ステップを再試行したときの扱いなど、ワークフローの設計は自分で担うことになります。購買プロセスであれば、その手間には意味があります。一方、データを読み、答えを計算して終了する範囲の限られた調査アシスタントには、構造が過剰になるかもしれません。

主な不確実性が*「どのPython処理を組み合わせれば、このタスクを解けるか」にあるならsmolagentsを選びます。「永続化された状態の間を、このプロセスがどう安全に進むか」*にあるならLangGraphを選びます。これは設計上の推奨であり、それぞれが特定の種類の仕事しかできないという意味ではありません。

OpenAI Agents SDK：引き継ぎ、チェック、トレースを重視する場合

専門エージェント同士の連携と運用上のチェックがアプリケーションの中心なら、OpenAI Agents SDKを第一候補にするとよいでしょう。 ハンドオフは会話の担当を別のエージェントに移し、agents-as-toolsパターンでは、管理役のエージェントが応答の責任を持ち続けます。オーケストレーションのドキュメント。

カスタマーサポートのアシスタントでは、汎用的にPythonで問題を解く仕組みよりも、請求の専門担当に会話を引き継ぐ仕組みのほうが、役割を明確に表せる場合があります。組み込みのトレース機能は、モデル呼び出し、ツール呼び出し、ハンドオフ、ガードレールを記録します。ガードレールは自動チェックを行い、人によるレビューの仕組みは、慎重な判断を要する操作を一時停止して判断を待ちます。トレース、ガードレールとレビュー。

それでも、アプリケーションのポリシーは利用側の課題として残ります。何に承認が必要かを決め、ツールを正しく実装し、中断された処理に対処する必要があります。これらの基本機能が、ポリシーまで作ってくれるわけではありません。また、SDKにはサンドボックス内でエージェントを動かす構成のドキュメントもあるため、コード実行はsmolagentsだけの機能ではありません。

Pythonで行動を組み立てることが必要な機能であり、小さなループで十分なら、smolagentsを選びます。連携やレビューの基本機能が構築するアプリケーションに合うなら、Agents SDKを選びます。「軽量」という理由だけでは、この比較に決着はつきません。

候補を広く検討したい場合は、AIエージェントフレームワークの比較を参照してください。開発の土台となるライブラリではなく、インストールして使うエージェントアプリケーションを探しているなら、オープンソースAIエージェントのガイドが出発点になります。

コードエージェントへの過度な期待を見直す

フレームワークが小さくても、予測しづらいタスクが予測可能になるわけではありません。 Pythonの表現力は役立ちますが、モデルが正しいレコードを選んだか、単位を正しく解釈したか、業務ルールを守ったかまでは保証できません。

処理を組み合わせられることを、あらゆる場面で速くなるという主張に置き換えないでください。操作をまとめれば実行の流れは変わりますが、結果を左右するのは依然としてモデル、タスク、ツールの動作、実行環境です。性能を理由に選ぶ前に、自分のタスクで測定してください。

具体的な制限も押さえておきましょう。現在のエージェントAPIでは、max_stepsのデフォルト値は20です。これはエージェントのステップ数を制限するもので、個々のPython処理が消費するリソースの上限ではありません。APIにはコールバック、マネージドエージェント、最終回答のチェックも用意されているため、シンプルな設計と制御機能がないことを混同すべきではありません。エージェントリファレンス。

運用では、実行時間とリソースの上限を別途設定する必要があります。ステップ数の上限はサンドボックスのポリシーの代わりにはならず、サンドボックスも結果の正しさを保証するものではありません。

来週から試すなら、何を作るか

範囲を限定し、答えを独立した方法で検証できる読み取り専用タスクから始めます。 smolagentsを評価するPython開発者なら、機密情報を除去した在庫のエクスポートデータと、用途を絞った検索ツールを使い、エージェントが指摘した不整合を既知の事例と照合する方法が考えられます。

正しいレコードを選んだか、ツールを正しく使ったか、想定した失敗から復旧できたか、設定した上限内で停止したかを記録します。決定論的な処理を比較の基準として残してください。タスクが常に同じ手順をたどるなら、その手順を通常のコードで記述します。Hugging Face自身も、可能な限り決定論的な関数を使う方針を推奨しています。良いエージェントの構築。

Pythonで処理を動的に組み立てる利点が、追加される複雑さに見合うなら、CodeAgentの導入を進めます。定義済みのツール群で足りるなら、ToolCallingAgentを使います。既存のワークフローがすでに要件を満たしているなら、移行を急ぐ必要はありません。承認待ちの状態を永続化することや、専門エージェントへの引き継ぎが中心になった段階で、フレームワークの選択を見直してください。

インストールと互換性のよくある質問

smolagentsをpipでインストールするには？

基本ライブラリはpip install smolagentsでインストールします。ツール、モデル、実行環境に応じて、必要な追加依存関係を入れてください。本記事のサンプルではsmolagents[docker]を使っています。

smolagentsのHfApiModelを使った古いサンプルはどう扱う？

新しく書くコードでは、現在のドキュメントにあるInferenceClientModelインターフェースに従います。古いサンプルのインポート文をそのまま使う前に、現行のモデルリファレンスで確認してください。

smolagentsでDockerを使うには？

Dockerをインストールして起動し、Docker向けの追加依存関係を入れて、executor_type="docker"を指定します。実行環境の分離は、処理内容に合わせて設定してください。この指定だけで、セキュリティポリシーが完成するわけではありません。

AI開発に役立つ実践的な情報をニュースレターで受け取る。