Native Tools

Read this file when the user wants provider-native tools such as web search, web fetch, code execution, memory, or file search.

Prefer provider-adaptive capabilities like WebSearch(), WebFetch(), MCP(), or ImageGeneration() when the user wants a provider-agnostic solution. Use native tools directly when they explicitly want provider-native behavior or provider-specific configuration.

Give My Agent Web Search or Code Execution

Native tools are wrapped in [NativeTool][pydantic_ai.capabilities.NativeTool] and passed via capabilities=[...].

from pydantic_ai import Agent
from pydantic_ai.capabilities import NativeTool
from pydantic_ai.native_tools import WebSearchTool

agent = Agent('openai-responses:gpt-5.2', name='web_search_agent', capabilities=[NativeTool(WebSearchTool())])
result = agent.run_sync('Give me a sentence with the biggest news in AI this week.')
print(result.output)

For OpenAI web search, use the Responses API model prefix (openai-responses:), not openai:. Set external_web_access=False on WebSearch or WebSearchTool to restrict OpenAI Responses web search to cached or indexed content.

Native Tool Defaults

Reach for these when the provider supports them:

• WebSearchTool
• WebFetchTool
• CodeExecutionTool
• ImageGenerationTool
• MemoryTool
• MCPServerTool
• FileSearchTool
• AdvisorTool (Anthropic, OpenRouter; lets a faster executor model consult a stronger advisor model mid-generation)

Dynamic Native Tool Configuration

Prepare native tools from RunContext when configuration depends on the current user or request. Wrap the prepare function in NativeTool(...).

from pydantic_ai import Agent, RunContext
from pydantic_ai.capabilities import NativeTool
from pydantic_ai.native_tools import WebSearchTool


async def prepared_web_search(ctx: RunContext[dict]) -> WebSearchTool | None:
    if not ctx.deps.get('location'):
        return None
    return WebSearchTool(user_location={'city': ctx.deps['location']})


agent = Agent(
    'openai-responses:gpt-5.2',
    name='dynamic_web_search_agent',
    capabilities=[NativeTool(prepared_web_search)],
    deps_type=dict,
)

Returning None omits the tool for that step. XSearch and ImageGeneration are the exception when fallback_subagent_model is set: they route unsupported models to a subagent rather than a local tool, and their native= factory is resolved a second time when that subagent runs. Once fallback_subagent_model is set, returning None no longer omits anything — the subagent tool stays offered and calling it raises UserError. Return a configured tool instance, or drop fallback_subagent_model.

When to Use Native Tools vs Provider-Adaptive Capabilities

Use provider-adaptive capabilities — WebSearch(), WebFetch(), MCP(), ImageGeneration() — when:

• the code should work across providers
• you want local fallback when native support is missing
• the user has not committed to a provider yet

from pydantic_ai import Agent
from pydantic_ai.capabilities import WebSearch

agent = Agent('anthropic:claude-sonnet-4-6', name='adaptive_web_search_agent', capabilities=[WebSearch()])

Use native tools (NativeTool(WebSearchTool(...))) when:

• the user explicitly wants provider-native behavior
• provider-specific configuration matters (e.g. WebSearchTool(user_location=...))
• the user already picked a provider that supports the tool