smolagents - コードファースト AI エージェントチートシート
smolagents はHugging Faceからの最小限のコードファースト AI エージェントライブラリです。その中心的な考え方は：モデルがツール呼び出しをJSONブロブとして発行する代わりに、CodeAgentは直接Pythonコードを書き実行します。アクションをコードとして表現することで、単一ステップで複数のツールを呼び出し、ループと変数を使用し、ロジックをチェーンできます。これにより、LLM往復の数が削減される (約30%少ない) ため、複雑なタスクでパフォーマンスが向上します。モデル不可知論で、サンドボックス実行をサポートし、意図的に小さく、ハッカブルな状態を保ちます。
インストール
| 方法 | コマンド |
|---|
| pip | pip install smolagents |
| ツールエクストラ付き | pip install "smolagents[toolkit]" |
| サンドボックスエクストラ | pip install "smolagents[e2b]" (または [docker]) |
| モデルキーを設定 | export HF_TOKEN=... またはプロバイダーキー |
| 確認 | python -c "import smolagents; print('ok')" |
コアコンセプト
| 用語 | 意味 |
|---|
| CodeAgent | Pythonアクションを書くエージェント (デフォルト) |
| ToolCallingAgent | クラシックJSONツール呼び出しを発行するエージェント |
| Tool | エージェントが使用できる呼び出し可能 (スキーマ付き) |
| Model | LLMバックエンド (HF、OpenAI、LiteLLM、ローカル) |
| Sandbox | 生成されたコードの実行場所 (ローカル、E2B、Docker、Modal) |
最小限のCodeAgent
from smolagents import CodeAgent, WebSearchTool, InferenceClientModel
agent = CodeAgent(
tools=[WebSearchTool()],
model=InferenceClientModel(), # HF Inference API
)
agent.run("How many seconds would it take a cheetah to cross the Golden Gate Bridge?")
| オブジェクト | 役割 |
|---|
CodeAgent(tools=[...], model=...) | エージェント |
agent.run("task") | エンドツーエンドでタスクを実行 |
WebSearchTool() | ビルトインツール |
InferenceClientModel() | HFホストモデルバックエンド |
モデル
| バックエンド | クラス |
|---|
| HF Inference API | InferenceClientModel |
| ローカル transformers | TransformersModel |
| LiteLLMを介したあらゆるプロバイダー | LiteLLMModel(model_id="openai/gpt-4o") |
| OpenAI互換サーバー | OpenAIServerModel(...) |
| vLLM / ローカルエンドポイント | LiteLLM / OpenAI互換経由 |
ツール定義
from smolagents import tool
@tool
def get_weather(city: str) -> str:
"""Return the weather for a city.
Args:
city: The city to look up.
"""
return f"Sunny in {city}"
agent = CodeAgent(tools=[get_weather], model=InferenceClientModel())
| メカニズム | 用途 |
|---|
@tool デコレーター | 型付き機能をツールに変換 |
Tool サブクラス | スキーマ/動作をより詳細に制御 |
| ツールコレクション | ツールセットをインポート (例：Hub) |
| MCPツール | モデルコンテキストプロトコルサーバーを接続 |
サンドボックス実行 (重要)
CodeAgentは生成されたPythonを実行するため、本番環境で分離します。
| サンドボックス | 方法 |
|---|
| ローカル (デフォルト) | プロセス内で実行 — 信頼できる開発のみ |
| E2B | executor_type="e2b" (リモートサンドボックス) |
| Docker | executor_type="docker" |
| Modal | リモートサンドボックス実行 |
| 許可されたインポート | 生成されたコードがインポートできるモジュールを制限 |
agent = CodeAgent(tools=[...], model=..., executor_type="e2b")
マルチエージェント & 検索
| パターン | 方法 |
|---|
| 管理されたエージェント | あるエージェントを他のエージェントにツールとして与える |
| 検索/RAG | グラウンド化された回答のためのレトリバーツール |
| 計画 | 難しいタスク用の定期的な計画ステップ |
| ハンドオフ | マネージャーエージェント下のスペシャリストを合成 |
一般的なワークフロー
# ブラウズしてコードで計算するリサーチエージェント
from smolagents import CodeAgent, WebSearchTool, InferenceClientModel
agent = CodeAgent(tools=[WebSearchTool()], model=InferenceClientModel(),
executor_type="docker")
agent.run("Compare the population growth of Tokyo and Delhi since 2000.")
smolagentsと他のエージェントフレームワーク
| 側面 | smolagents | LangGraph | Pydantic AI |
|---|
| アクション形式 | Pythonコード | グラフ/ステートマシン | 型付きツール呼び出し |
| サイズ/哲学 | 最小限、ハッカブル | 完全な状態オーケストレーション | タイプセーフ、FastAPIスタイル |
| LLM効率 | より少ないコール (コード) | 依存する | 標準 |
| 最適用途 | シングルエージェントコードループ | 耐久的なステートフルエージェント | タイプセーフ本番エージェント |
リソース
