ag2-use-builtin-tools

AG2 の組み込みツールを使う

使用するタイミング

ユーザーが、AG2 にすでに同梱されている機能の追加を希望している場合に、このスキルを使います。次の 2 種類があります。

1. プロバイダー固有のツール（ag2.tools — WebSearchTool、CodeExecutionTool など）— Anthropic／OpenAI／Gemini がサーバー側で実行します。こちらで Python の実装を用意する必要はありません。
2. 一般的なツールキット（ag2.tools — FilesystemToolkit、DuckDuckSearchTool、TavilySearchTool、SkillsToolkit、および ag2.extensions.tools.search の ExaToolkit）— プロセス内で実行される通常の Python で、すべてのプロバイダーで動作します。

シェルコマンドには ag2-shell-tool を使います（独立したスキルとして扱うほど重要です）。 カスタム Python ツールには ag2-add-custom-tool を使います。

60 秒でできるレシピ

ウェブ検索（プロバイダー固有）

from ag2 import Agent
from ag2.config import AnthropicConfig
from ag2.tools import WebSearchTool, UserLocation

agent = Agent(
    "researcher",
    config=AnthropicConfig(model="claude-sonnet-4-6"),
    tools=[
        WebSearchTool(
            max_uses=5,
            user_location=UserLocation(country="US"),
            allowed_domains=["github.com", "pypi.org"],
            blocked_domains=["pinterest.com"],
        ),
    ],
)

ウェブ取得（Anthropic／Gemini のみ）

from ag2.tools import WebFetchTool

tools = [WebFetchTool(max_uses=3, max_content_tokens=50000, citations=True)]

コード実行

from ag2.tools import CodeExecutionTool

agent = Agent("analyst", config=config, tools=[CodeExecutionTool()])

MCP サーバーの統合

from ag2.tools import MCPServerTool

tools = [
    MCPServerTool(
        server_url="https://mcp.example.com/sse",
        server_label="my-tools",
        allowed_tools=["search", "summarize"],
    ),
]

画像生成（OpenAI Responses のみ）

from ag2.config import OpenAIResponsesConfig
from ag2.tools import ImageGenerationTool

agent = Agent(
    "designer",
    config=OpenAIResponsesConfig(model="gpt-4.1"),
    tools=[ImageGenerationTool(quality="high", size="1024x1024", output_format="png")],
)
reply = await agent.ask("Generate a logo for a coffee shop.")
images = reply.files  # list[BinaryResult]

ファイルシステム（サンドボックス化、すべてのプロバイダーに対応）

from ag2.tools import FilesystemToolkit

fs = FilesystemToolkit(base_path="/tmp/workspace")
agent = Agent("worker", config=config, tools=[fs])

base_path によってアクセスが制限されており、../../etc/passwd は PermissionError を発生させます。read_only=True を使うと、read_file と find_files のみを公開できます。一時的なワークスペースには、/tmp をハードコードするのではなく、tempfile.TemporaryDirectory() を使います。

DuckDuckGo によるウェブ検索（API キー不要）

from ag2.tools import DuckDuckSearchTool
# requires: pip install ag2[ddgs]

tools = [DuckDuckSearchTool(max_results=10, region="us-en", safesearch="moderate")]

Exa ニューラル検索

import os
from ag2.extensions.tools.search import ExaToolkit
# requires: pip install "exa-py>=2.12.1,<3"  (no ag2[exa] extra — install the package directly)

tools = [ExaToolkit(api_key=os.environ["EXA_API_KEY"])]

各ツールはファクトリーメソッド（exa.search()、exa.find_similar()、exa.get_contents()、exa.answer()）として公開されるため、呼び出しごとの設定を使って、必要なものだけを渡せます。

Tavily 検索

import os
from ag2.tools import TavilySearchTool
# requires: pip install ag2[tavily]

tools = [TavilySearchTool(
    api_key=os.environ["TAVILY_API_KEY"],
    search_depth="advanced",
    include_answer=True,
)]

さらに詳しく

• ツールごとのプロバイダー対応状況、全パラメーター、バージョンの固定 — references/builtin_tools_matrix.md。
• ソースドキュメント — website/docs/user-guide/tools/builtin_tools.mdx（プロバイダー固有）、website/docs/user-guide/tools/common_toolkits.mdx（一般的なツールキット — SkillsToolkit と SkillSearchToolkit についても説明しています）。
• ツールキットの作成 — website/docs/user-guide/tools/toolkits.mdx。

よくある落とし穴

• ツールとプロバイダーの不一致 — OpenAI で WebFetchTool を使うとエラーになり、MemoryTool は Anthropic 専用、ImageGenerationTool は OpenAI Responses 専用です。まず references/builtin_tools_matrix.md を確認してください。
• Anthropic のツールバージョンは古いリビジョンがデフォルトです — Opus 4.6／Sonnet 4.6 で動的フィルタリングが必要な場合は、version="web_search_20260209" などを指定してください。
• FilesystemToolkit のパスはサンドボックス化されています — これは仕様です。パストラバーサルのガードを回避しようとせず、代わりに base_path を広く設定してください。
• ツールキットと個別のツールは自由に組み合わせられます — tools=[fs, exa, my_custom_tool] のように指定できます。
• オプションの依存関係が不足している — DuckDuckSearchTool（ag2[ddgs]）と TavilySearchTool（ag2[tavily]）には、それぞれ ag2[<extra>] のインストールが必要です。ExaToolkit は ag2 の追加機能ではなく拡張機能のため、パッケージを直接インストールしてください（pip install "exa-py>=2.12.1,<3"）。依存関係がない場合、わかりにくいクラッシュではなく、設定フォールバック層から明確な ImportError が発生します。コードを渡す前にインストールしてください。コマンドを実行できない場合は、正確な pip install コマンドを記載してください。