- remove builtin_tools suport check for specific models, base model takes care

- swap builtin tool getters for public constans and inline checks
- move agent loader and private web module into locally public scopes

Author: dsfaccini

pydantic_ai_slim/pydantic_ai/_cli/__init__.py

@@ -10,6 +10,7 @@
 from pathlib import Path
 from typing import Any, cast
 
+from pydantic import ImportString, TypeAdapter, ValidationError
 from typing_inspection.introspection import get_literal_values
 
 from .. import __version__
@@ -83,6 +84,27 @@ def __rich_console__(self, console: Console, options: ConsoleOptions) -> RenderR
 
 cli_agent = Agent()
 
+_import_string_adapter: TypeAdapter[Any] = TypeAdapter(ImportString)
+
+
+def load_agent(agent_path: str) -> Agent[Any, Any] | None:
+    """Load an agent from module path in uvicorn style.
+
+    Args:
+        agent_path: Path in format 'module:variable', e.g. 'test_agent:my_agent'
+
+    Returns:
+        Agent instance or None if loading fails
+    """
+    sys.path.insert(0, str(Path.cwd()))
+    try:
+        obj = _import_string_adapter.validate_python(agent_path)
+        if not isinstance(obj, Agent):
+            return None
+        return obj  # pyright: ignore[reportUnknownVariableType]
+    except ValidationError:
+        return None
+
 
 @cli_agent.system_prompt
 def cli_system_prompt() -> str:
@@ -200,9 +222,9 @@ def cli(  # noqa: C901
     args = parser.parse_args(args_list)
 
     if prog_name == 'clai' and getattr(args, 'command', None) == 'web':
-        from ._web import _run_web_command  # pyright: ignore[reportPrivateUsage]
+        from .web import run_web_command
 
-        return _run_web_command(
+        return run_web_command(
             agent_path=args.agent,
             host=args.host,
             port=args.port,
@@ -225,9 +247,7 @@ def cli(  # noqa: C901
 
     agent: Agent[None, str] = cli_agent
     if args.agent:
-        from ._web import _load_agent  # pyright: ignore[reportPrivateUsage]
-
-        loaded = _load_agent(args.agent)
+        loaded = load_agent(args.agent)
         if loaded is None:
             console.print(f'[red]Error: Could not load agent from {args.agent}[/red]')
             return 1

pydantic_ai_slim/pydantic_ai/_cli/_web.py pydantic_ai_slim/pydantic_ai/_cli/web.pypydantic_ai_slim/pydantic_ai/_cli/_web.py renamed to pydantic_ai_slim/pydantic_ai/_cli/web.py

@@ -1,45 +1,26 @@
-"""CLI command for launching a web chat UI for agents."""
-
 from __future__ import annotations
 
-import sys
-from pathlib import Path
-from typing import Any
-
-from pydantic import ImportString, TypeAdapter, ValidationError
+from pydantic import ValidationError
 from rich.console import Console
 
 from pydantic_ai import Agent
-from pydantic_ai.builtin_tools import AbstractBuiltinTool, get_builtin_tool_cls
+from pydantic_ai.builtin_tools import (
+    BUILTIN_TOOL_TYPES,
+    DEPRECATED_BUILTIN_TOOL_TYPES,
+    AbstractBuiltinTool,
+)
 from pydantic_ai.mcp import MCPServerSSE, MCPServerStdio, MCPServerStreamableHTTP, load_mcp_servers
 from pydantic_ai.models import infer_model
 from pydantic_ai.ui._web import create_web_app
 
-__all__ = ['_run_web_command']
-
-_import_string_adapter: TypeAdapter[Any] = TypeAdapter(ImportString)
+from . import load_agent
 
+# Tools that require configuration and cannot be enabled via CLI
+# (includes deprecated tools plus tools needing config like mcp_server and memory)
+UNSUPPORTED_CLI_TOOLS = DEPRECATED_BUILTIN_TOOL_TYPES | frozenset({'mcp_server', 'memory'})
 
-def _load_agent(agent_path: str) -> Agent | None:
-    """Load an agent from module path in uvicorn style.
 
-    Args:
-        agent_path: Path in format 'module:variable', e.g. 'test_agent:my_agent'
-
-    Returns:
-        Agent instance or None if loading fails
-    """
-    sys.path.insert(0, str(Path.cwd()))
-    try:
-        obj = _import_string_adapter.validate_python(agent_path)
-        if not isinstance(obj, Agent):
-            return None
-        return obj  # pyright: ignore[reportUnknownVariableType]
-    except ValidationError:
-        return None
-
-
-def _run_web_command(  # noqa: C901
+def run_web_command(  # noqa: C901
     agent_path: str | None = None,
     host: str = '127.0.0.1',
     port: int = 7932,
@@ -66,7 +47,7 @@ def _run_web_command(  # noqa: C901
     console = Console()
 
     if agent_path:
-        agent = _load_agent(agent_path)
+        agent = load_agent(agent_path)
         if agent is None:
             console.print(f'[red]Error: Could not load agent from {agent_path}[/red]')
             return 1
@@ -92,12 +73,14 @@ def _run_web_command(  # noqa: C901
     # then CLI tools
     if tools:
         for tool_id in tools:
-            tool_cls = get_builtin_tool_cls(tool_id)
-            if tool_cls is None or tool_id in ('url_context', 'mcp_server'):
-                console.print(f'[yellow]Warning: Unknown tool "{tool_id}", skipping[/yellow]')
+            if tool_id in UNSUPPORTED_CLI_TOOLS:
+                console.print(
+                    f'[yellow]Warning: "{tool_id}" requires configuration and cannot be enabled via CLI, skipping[/yellow]'
+                )
                 continue
-            if tool_id == 'memory':
-                console.print('[yellow]Warning: MemoryTool requires agent to have memory configured, skipping[/yellow]')
+            tool_cls = BUILTIN_TOOL_TYPES.get(tool_id)
+            if tool_cls is None:
+                console.print(f'[yellow]Warning: Unknown tool "{tool_id}", skipping[/yellow]')
                 continue
             all_tool_instances.append(tool_cls())
 
@@ -120,8 +103,8 @@ def _run_web_command(  # noqa: C901
     app = create_web_app(
         agent,
         models=models,
-        builtin_tools=all_tool_instances if all_tool_instances else None,
-        toolsets=mcp_servers if mcp_servers else None,
+        builtin_tools=all_tool_instances or None,
+        toolsets=mcp_servers or None,
     )
 
     agent_desc = agent_path if agent_path else 'generic agent'

pydantic_ai_slim/pydantic_ai/builtin_tools.py

@@ -18,12 +18,19 @@
     'ImageGenerationTool',
     'MemoryTool',
     'MCPServerTool',
-    'get_builtin_tool_ids',
+    'BUILTIN_TOOL_TYPES',
+    'DEPRECATED_BUILTIN_TOOL_TYPES',
     'get_builtin_tool_types',
-    'get_builtin_tool_cls',
 )
 
-_BUILTIN_TOOL_TYPES: dict[str, type[AbstractBuiltinTool]] = {}
+BUILTIN_TOOL_TYPES: dict[str, type[AbstractBuiltinTool]] = {}
+"""Registry of all builtin tool types, keyed by their kind string.
+
+This dict is populated automatically via `__init_subclass__` when tool classes are defined.
+"""
+
+DEPRECATED_BUILTIN_TOOL_TYPES: frozenset[str] = frozenset({'url_context'})
+"""Set of deprecated builtin tool IDs that should not be offered in new UIs."""
 
 
 @dataclass(kw_only=True)
@@ -56,7 +63,7 @@ def label(self) -> str:
 
     def __init_subclass__(cls, **kwargs: Any) -> None:
         super().__init_subclass__(**kwargs)
-        _BUILTIN_TOOL_TYPES[cls.kind] = cls
+        BUILTIN_TOOL_TYPES[cls.kind] = cls
 
     @classmethod
     def __get_pydantic_core_schema__(
@@ -65,7 +72,7 @@ def __get_pydantic_core_schema__(
         if cls is not AbstractBuiltinTool:
             return handler(cls)
 
-        tools = _BUILTIN_TOOL_TYPES.values()
+        tools = BUILTIN_TOOL_TYPES.values()
         if len(tools) == 1:  # pragma: no cover
             tools_type = next(iter(tools))
         else:
@@ -417,20 +424,7 @@ def _tool_discriminator(tool_data: dict[str, Any] | AbstractBuiltinTool) -> str:
         return tool_data.kind
 
 
-def get_builtin_tool_ids() -> frozenset[str]:  # pragma: no cover
-    """Get the set of all builtin tool IDs (excluding deprecated tools like url_context)."""
-    return frozenset(_BUILTIN_TOOL_TYPES.keys() - {'url_context'})
-
-
+# This function exists primarily as a clean default_factory for ModelProfile.supported_builtin_tools
 def get_builtin_tool_types() -> frozenset[type[AbstractBuiltinTool]]:
-    """Get the set of all builtin tool types (excluding deprecated tools like UrlContextTool)."""
-    return frozenset(cls for kind, cls in _BUILTIN_TOOL_TYPES.items() if kind != 'url_context')
-
-
-def get_builtin_tool_cls(tool_id: str) -> type[AbstractBuiltinTool] | None:
-    """Get a builtin tool class by its ID.
-
-    Args:
-        tool_id: The tool ID (e.g., 'web_search', 'code_execution')
-    """
-    return _BUILTIN_TOOL_TYPES.get(tool_id)
+    """Get the set of all builtin tool types (excluding deprecated tools)."""
+    return frozenset(cls for kind, cls in BUILTIN_TOOL_TYPES.items() if kind not in DEPRECATED_BUILTIN_TOOL_TYPES)

pydantic_ai_slim/pydantic_ai/models/anthropic.py

@@ -263,7 +263,7 @@ def system(self) -> str:
 
     @classmethod
     def supported_builtin_tools(cls) -> frozenset[type[AbstractBuiltinTool]]:
-        """Return the set of builtin tool types this model can handle."""
+        """The set of builtin tool types this model can handle."""
         return frozenset({WebSearchTool, CodeExecutionTool, WebFetchTool, MemoryTool, MCPServerTool})
 
     async def request(

pydantic_ai_slim/pydantic_ai/models/bedrock.py

@@ -40,7 +40,7 @@
     usage,
 )
 from pydantic_ai._run_context import RunContext
-from pydantic_ai.exceptions import ModelAPIError, ModelHTTPError, UserError
+from pydantic_ai.exceptions import ModelAPIError, ModelHTTPError
 from pydantic_ai.models import Model, ModelRequestParameters, StreamedResponse, download_item
 from pydantic_ai.providers import Provider, infer_provider
 from pydantic_ai.providers.bedrock import BedrockModelProfile
@@ -433,10 +433,6 @@ async def _messages_create(
         if tool_config:
             params['toolConfig'] = tool_config
 
-        if model_request_parameters.builtin_tools:  # pragma: no cover
-            # this check is done in the base Model class - leave this as a placeholder for when Bedrock supports built-in tools
-            raise UserError('Bedrock does not support built-in tools')
-
         # Bedrock supports a set of specific extra parameters
         if model_settings:
             if guardrail_config := model_settings.get('bedrock_guardrail_config', None):

pydantic_ai_slim/pydantic_ai/models/function.py

@@ -204,9 +204,9 @@ def system(self) -> str:
     @classmethod
     def supported_builtin_tools(cls) -> frozenset[type[AbstractBuiltinTool]]:
         """FunctionModel supports all builtin tools for testing flexibility."""
-        from ..builtin_tools import get_builtin_tool_types
+        from ..builtin_tools import BUILTIN_TOOL_TYPES, DEPRECATED_BUILTIN_TOOL_TYPES
 
-        return get_builtin_tool_types()
+        return frozenset(cls for kind, cls in BUILTIN_TOOL_TYPES.items() if kind not in DEPRECATED_BUILTIN_TOOL_TYPES)
 
 
 @dataclass(frozen=True, kw_only=True)

pydantic_ai_slim/pydantic_ai/models/huggingface.py

@@ -12,7 +12,6 @@
 from .._run_context import RunContext
 from .._thinking_part import split_content_into_text_and_thinking
 from .._utils import guard_tool_call_id as _guard_tool_call_id, now_utc as _now_utc
-from ..exceptions import UserError
 from ..messages import (
     AudioUrl,
     BinaryContent,
@@ -229,10 +228,6 @@ async def _completions_create(
         else:
             tool_choice = 'auto'
 
-        if model_request_parameters.builtin_tools:  # pragma: no cover
-            # this check is done in the base Model class - leave this as a placeholder for when Bedrock supports built-in tools
-            raise UserError('HuggingFace does not support built-in tools')
-
         hf_messages = await self._map_messages(messages, model_request_parameters)
 
         try:

pydantic_ai_slim/pydantic_ai/models/mistral.py

@@ -13,7 +13,7 @@
 from .. import ModelHTTPError, UnexpectedModelBehavior, _utils
 from .._run_context import RunContext
 from .._utils import generate_tool_call_id as _generate_tool_call_id, now_utc as _now_utc, number_to_datetime
-from ..exceptions import ModelAPIError, UserError
+from ..exceptions import ModelAPIError
 from ..messages import (
     BinaryContent,
     BuiltinToolCallPart,
@@ -224,10 +224,6 @@ async def _completions_create(
         """Make a non-streaming request to the model."""
         # TODO(Marcelo): We need to replace the current MistralAI client to use the beta client.
         # See https://docs.mistral.ai/agents/connectors/websearch/ to support web search.
-        if model_request_parameters.builtin_tools:  # pragma: no cover
-            # this check is done in the base Model class - leave this as a placeholder for when Bedrock supports built-in tools
-            raise UserError('Mistral does not support built-in tools')
-
         try:
             response = await self.client.chat.complete_async(
                 model=str(self._model_name),
@@ -264,9 +260,6 @@ async def _stream_completions_create(
 
         # TODO(Marcelo): We need to replace the current MistralAI client to use the beta client.
         # See https://docs.mistral.ai/agents/connectors/websearch/ to support web search.
-        if model_request_parameters.builtin_tools:  # pragma: no cover
-            raise UserError('Mistral does not support built-in tools')
-
         if model_request_parameters.function_tools:
             # Function Calling
             response = await self.client.chat.stream_async(

pydantic_ai_slim/pydantic_ai/models/test.py

@@ -161,9 +161,9 @@ def system(self) -> str:
     @classmethod
     def supported_builtin_tools(cls) -> frozenset[type[AbstractBuiltinTool]]:
         """TestModel supports all builtin tools for testing flexibility."""
-        from ..builtin_tools import get_builtin_tool_types
+        from ..builtin_tools import BUILTIN_TOOL_TYPES, DEPRECATED_BUILTIN_TOOL_TYPES
 
-        return get_builtin_tool_types()
+        return frozenset(c for kind, c in BUILTIN_TOOL_TYPES.items() if kind not in DEPRECATED_BUILTIN_TOOL_TYPES)
 
     def gen_tool_args(self, tool_def: ToolDefinition) -> Any:
         return _JsonSchemaTestData(tool_def.parameters_json_schema, self.seed).generate()