add support for model instances, deps and settings

Author: dsfaccini

pydantic_ai_slim/pydantic_ai/_cli/__init__.py

@@ -57,9 +57,7 @@
 
 # CLI-supported tool IDs (excludes deprecated and config-requiring tools)
 _CLI_TOOL_IDS = sorted(
-    k.kind
-    for k in get_builtin_tool_types()
-    if k not in {'mcp_server', 'memory', 'unknown_builtin_tool'}
+    k.kind for k in get_builtin_tool_types() if k not in {'mcp_server', 'memory', 'unknown_builtin_tool'}
 )
 
 

pydantic_ai_slim/pydantic_ai/agent/__init__.py

@@ -1488,6 +1488,9 @@ def to_web(
         | dict[str, models.Model | models.KnownModelName | str]
         | None = None,
         builtin_tools: list[AbstractBuiltinTool] | None = None,
+        deps: AgentDepsT = None,
+        model_settings: ModelSettings | None = None,
+        instructions: str | None = None,
     ) -> Starlette:
         """Create a Starlette app that serves a web chat UI for this agent.
 
@@ -1498,16 +1501,22 @@ def to_web(
         The returned Starlette application can be mounted into a FastAPI app or run directly
         with any ASGI server (uvicorn, hypercorn, etc.).
 
+        Note that the `deps` and `model_settings` will be the same for each request.
+        To provide different `deps` for each request use the lower-level adapters directly.
+
         Args:
             models: Models to make available in the UI. Can be:
                 - A sequence of model names/instances (e.g., `['openai:gpt-5', 'anthropic:claude-sonnet-4-5']`)
                 - A dict mapping display labels to model names/instances
                   (e.g., `{'GPT 5': 'openai:gpt-5', 'Claude': 'anthropic:claude-sonnet-4-5'}`)
-                If not provided, the UI will have no model options.
+                If not provided, uses the agent's configured model.
                 Builtin tool support is automatically determined from each model's profile.
-            builtin_tools: Builtin tools to make available. If not provided, no tools
-                will be available. Tool labels in the UI are derived from the tool's
-                `label` property.
+            builtin_tools: Builtin tools to make available. If not provided, uses the
+                agent's configured builtin tools. Tool labels in the UI are derived
+                from the tool's `label` property.
+            deps: Optional dependencies to use for all requests.
+            model_settings: Optional settings to use for all model requests.
+            instructions: Optional extra instructions to pass to each agent run.
 
         Returns:
             A configured Starlette application ready to be served (e.g., with uvicorn)
@@ -1517,30 +1526,32 @@ def to_web(
             from pydantic_ai import Agent
             from pydantic_ai.builtin_tools import WebSearchTool
 
-            agent = Agent('openai:gpt-5')
+            agent = Agent('openai:gpt-5', builtin_tools=[WebSearchTool()])
 
-            @agent.tool_plain
-            def get_weather(city: str) -> str:
-                return f'The weather in {city} is sunny'
-
-            # With model names (display names auto-generated)
-            app = agent.to_web(
-                models=['openai:gpt-5', 'anthropic:claude-sonnet-4-5'],
-                builtin_tools=[WebSearchTool()],
-            )
+            # Simple usage - uses agent's model and builtin tools
+            app = agent.to_web()
 
-            # Or with custom display labels
-            app = agent.to_web(
-                models={'GPT 5': 'openai:gpt-5', 'Claude': 'anthropic:claude-sonnet-4-5'},
-                builtin_tools=[WebSearchTool()],
-            )
+            # Or provide additional models for UI selection
+            app = agent.to_web(models=['openai:gpt-5', 'anthropic:claude-sonnet-4-5'])
 
             # Then run with: uvicorn app:app --reload
             ```
         """
-        from ..ui._web import create_web_app
+        from ..ui._web import ModelsParam, create_web_app
+
+        # weird ternary for typing purposes
+        resolved_models: ModelsParam = models or (self._model and [self._model])
+
+        resolved_builtin_tools = builtin_tools or list(self._builtin_tools)
 
-        return create_web_app(self, models=models, builtin_tools=builtin_tools)
+        return create_web_app(
+            self,
+            models=resolved_models,
+            builtin_tools=resolved_builtin_tools,
+            deps=deps,
+            model_settings=model_settings,
+            instructions=instructions,
+        )
 
     @asynccontextmanager
     @deprecated(

pydantic_ai_slim/pydantic_ai/models/__init__.py

@@ -489,12 +489,13 @@ def prepare_request(
         # Check if builtin tools are supported
         if params.builtin_tools:
             supported_types = self.profile.supported_builtin_tools
-            for tool in params.builtin_tools:
-                if not isinstance(tool, tuple(supported_types)):
-                    raise UserError(
-                        f'Builtin tool {type(tool).__name__} is not supported by this model. '
-                        f'Supported tools: {[t.__name__ for t in supported_types]}'
-                    )
+            unsupported = [tool for tool in params.builtin_tools if not isinstance(tool, tuple(supported_types))]
+            if unsupported:
+                unsupported_names = [type(tool).__name__ for tool in unsupported]
+                supported_names = [t.__name__ for t in supported_types]
+                raise UserError(
+                    f'Builtin tool(s) {unsupported_names} not supported by this model. Supported: {supported_names}'
+                )
 
         return model_settings, params
 
@@ -506,8 +507,34 @@ def model_name(self) -> str:
 
     @property
     def label(self) -> str:
-        """Human-friendly display label for the model."""
-        return _format_model_label(self.model_name)
+        """Human-friendly display label for the model.
+
+        Handles common patterns:
+        - gpt-5 -> GPT 5
+        - claude-sonnet-4-5 -> Claude Sonnet 4.5
+        - gemini-2.5-pro -> Gemini 2.5 Pro
+        - meta-llama/llama-3-70b -> Llama 3 70b (OpenRouter style)
+        """
+        label = self.model_name
+        # Handle OpenRouter-style names with / (e.g., meta-llama/llama-3-70b)
+        if '/' in label:
+            label = label.split('/')[-1]
+
+        parts = label.split('-')
+        result: list[str] = []
+
+        for i, part in enumerate(parts):
+            if i == 0 and part.lower() == 'gpt':
+                result.append(part.upper())
+            elif part.replace('.', '').isdigit():
+                if result and result[-1].replace('.', '').isdigit():
+                    result[-1] = f'{result[-1]}.{part}'
+                else:
+                    result.append(part)
+            else:
+                result.append(part.capitalize())
+
+        return ' '.join(result)
 
     @classmethod
     def supported_builtin_tools(cls) -> frozenset[type[AbstractBuiltinTool]]:
@@ -756,36 +783,6 @@ def timestamp(self) -> datetime:
 """
 
 
-def _format_model_label(model_name: str) -> str:
-    """Format model name for display in UI.
-
-    Handles common patterns:
-    - gpt-5 -> GPT 5
-    - claude-sonnet-4-5 -> Claude Sonnet 4.5
-    - gemini-2.5-pro -> Gemini 2.5 Pro
-    - meta-llama/llama-3-70b -> Llama 3 70b (OpenRouter style)
-    """
-    # Handle OpenRouter-style names with / (e.g., meta-llama/llama-3-70b)
-    if '/' in model_name:
-        model_name = model_name.split('/')[-1]
-
-    parts = model_name.split('-')
-    result: list[str] = []
-
-    for i, part in enumerate(parts):
-        if i == 0 and part.lower() == 'gpt':
-            result.append(part.upper())
-        elif part.replace('.', '').isdigit():
-            if result and result[-1].replace('.', '').isdigit():
-                result[-1] = f'{result[-1]}.{part}'
-            else:
-                result.append(part)
-        else:
-            result.append(part.capitalize())
-
-    return ' '.join(result)
-
-
 def check_allow_model_requests() -> None:
     """Check if model requests are allowed.
 

pydantic_ai_slim/pydantic_ai/ui/_web/api.py

@@ -1,7 +1,7 @@
 """API routes for the web chat UI."""
 
 from collections.abc import Sequence
-from typing import Any
+from typing import TypeVar
 
 from pydantic import BaseModel
 from pydantic.alias_generators import to_camel
@@ -11,9 +11,13 @@
 
 from pydantic_ai import Agent
 from pydantic_ai.builtin_tools import AbstractBuiltinTool
+from pydantic_ai.settings import ModelSettings
 from pydantic_ai.toolsets import AbstractToolset
 from pydantic_ai.ui.vercel_ai import VercelAIAdapter
 
+AgentDepsT = TypeVar('AgentDepsT')
+OutputDataT = TypeVar('OutputDataT')
+
 
 class ModelInfo(BaseModel, alias_generator=to_camel, populate_by_name=True):
     """Defines an AI model with its associated built-in tools."""
@@ -30,14 +34,14 @@ class BuiltinToolInfo(BaseModel, alias_generator=to_camel, populate_by_name=True
     name: str
 
 
-class _ConfigureFrontend(BaseModel, alias_generator=to_camel, populate_by_name=True):
+class ConfigureFrontend(BaseModel, alias_generator=to_camel, populate_by_name=True):
     """Response model for frontend configuration."""
 
     models: list[ModelInfo]
     builtin_tools: list[BuiltinToolInfo]
 
 
-class _ChatRequestExtra(BaseModel, extra='ignore', alias_generator=to_camel):
+class ChatRequestExtra(BaseModel, extra='ignore', alias_generator=to_camel):
     """Extra data extracted from chat request."""
 
     model: str | None = None
@@ -46,12 +50,39 @@ class _ChatRequestExtra(BaseModel, extra='ignore', alias_generator=to_camel):
     """Tool IDs selected by the user, e.g. ['web_search', 'code_execution']. Maps to JSON field 'builtinTools'."""
 
 
+def validate_request_options(
+    extra_data: ChatRequestExtra,
+    model_ids: set[str],
+    allowed_tool_ids: set[str],
+) -> str | None:
+    """Validate that requested model and tools are in the allowed lists.
+
+    Returns an error message if validation fails, or None if valid.
+    """
+    if extra_data.model and model_ids and extra_data.model not in model_ids:
+        return f'Model "{extra_data.model}" is not in the allowed models list'
+
+    # base model also valdiates this but makes sesne to have an api check, since one could be a UI bug/misbehavior
+    # the other would be a pydantic-ai bug
+    # also as future proofing since we don't know how users will use this feature in the future
+    invalid_tools = [t for t in extra_data.builtin_tools if t not in allowed_tool_ids]
+    if invalid_tools:
+        return f'Builtin tool(s) {invalid_tools} not in the allowed tools list'
+
+    return None
+
+
+# TODO remove the app arg and return a router instead (refactor the upstream logic to mount the router)
+# https://github.com/pydantic/pydantic-ai/pull/3456/files#r2582659204
 def add_api_routes(
     app: Starlette,
-    agent: Agent,
+    agent: Agent[AgentDepsT, OutputDataT],
     models: list[ModelInfo] | None = None,
     builtin_tools: list[AbstractBuiltinTool] | None = None,
-    toolsets: Sequence[AbstractToolset[Any]] | None = None,
+    toolsets: Sequence[AbstractToolset[AgentDepsT]] | None = None,
+    deps: AgentDepsT = None,
+    model_settings: ModelSettings | None = None,
+    instructions: str | None = None,
 ) -> None:
     """Add API routes to a Starlette app.
 
@@ -61,22 +92,25 @@ def add_api_routes(
         models: Optional list of AI models. If not provided, the UI will have no model options.
         builtin_tools: Optional list of builtin tools. If not provided, no tools will be available.
         toolsets: Optional list of toolsets (e.g., MCP servers). These provide additional tools.
+        deps: Optional dependencies to use for all requests.
+        model_settings: Optional settings to use for all model requests.
+        instructions: Optional extra instructions to pass to each agent run.
     """
-    _models = models or []
-    _model_ids = {m.id for m in _models}
-    _builtin_tools = builtin_tools or []
-    _toolsets = list(toolsets) if toolsets else None
-    _tools_by_id: dict[str, AbstractBuiltinTool] = {tool.unique_id: tool for tool in _builtin_tools}
+    models = models or []
+    model_ids = {m.id for m in models}
+    builtin_tools = builtin_tools or []
+    allowed_tool_ids = {tool.unique_id for tool in builtin_tools}
+    toolsets = list(toolsets) if toolsets else None
 
     async def options_chat(request: Request) -> Response:
         """Handle CORS preflight requests."""
         return Response()
 
     async def configure_frontend(request: Request) -> Response:
         """Endpoint to configure the frontend with available models and tools."""
-        config = _ConfigureFrontend(
-            models=_models,
-            builtin_tools=[BuiltinToolInfo(id=tool.unique_id, name=tool.label) for tool in _builtin_tools],
+        config = ConfigureFrontend(
+            models=models,
+            builtin_tools=[BuiltinToolInfo(id=tool.unique_id, name=tool.label) for tool in builtin_tools],
         )
         return JSONResponse(config.model_dump(by_alias=True))
 
@@ -86,25 +120,22 @@ async def health(request: Request) -> Response:
 
     async def post_chat(request: Request) -> Response:
         """Handle chat requests via Vercel AI Adapter."""
-        adapter = await VercelAIAdapter.from_request(request, agent=agent)
-        extra_data = _ChatRequestExtra.model_validate(adapter.run_input.__pydantic_extra__)
-
-        # Validate model is in allowed list
-        if extra_data.model and _model_ids and extra_data.model not in _model_ids:
-            return JSONResponse(
-                {'error': f'Model "{extra_data.model}" is not in the allowed models list'},
-                status_code=400,
-            )
-
-        request_builtin_tools = [
-            _tools_by_id[tool_id] for tool_id in extra_data.builtin_tools if tool_id in _tools_by_id
-        ]
-        streaming_response = await VercelAIAdapter.dispatch_request(
+        adapter = await VercelAIAdapter[AgentDepsT, OutputDataT].from_request(request, agent=agent)
+        extra_data = ChatRequestExtra.model_validate(adapter.run_input.__pydantic_extra__)
+
+        if error := validate_request_options(extra_data, model_ids, allowed_tool_ids):
+            return JSONResponse({'error': error}, status_code=400)
+
+        request_builtin_tools = [tool for tool in builtin_tools if tool.unique_id in extra_data.builtin_tools]
+        streaming_response = await VercelAIAdapter[AgentDepsT, OutputDataT].dispatch_request(
             request,
             agent=agent,
             model=extra_data.model,
             builtin_tools=request_builtin_tools,
-            toolsets=_toolsets,
+            toolsets=toolsets,
+            deps=deps,
+            model_settings=model_settings,
+            instructions=instructions,
         )
         return streaming_response