Add Agent.to_web() method and web chat UI #3456

dsfaccini · 2025-11-17T18:27:44Z

web-based chat interface for Pydantic AI agents

new module pydantic_ai.ui.web
new method Agent.to_web()

fastapi

app = create_chat_app(agent)
the following endpoints come preconfigured:
- GET / and /:id - serve the chat UI
- POST /api/chat - Main chat endpoint using VercelAIAdapter
- GET /api/configure - Returns available models and builtin tools
- GET /api/health - Health check
- NOTE: I'm counting on FastAPI to complain if the user tried adding conflicting routes, otherwise we could add a warning on the respective docs.

options and example

NOTE: the module for options is currently pydantic_ai.ui.web.

pre-configured model options:
- anthropic:claude-sonnet-4-5
- openai-responses:gpt-5
- google-gla:gemini-2.5-pro
supported builtin tools:
- web_search
- code_execution
- image_generation

# app.py
import logfire
from pydantic_ai import Agent

logfire.configure(send_to_logfire='if-token-present')
logfire.instrument_pydantic_ai()

agent = Agent('openai:gpt-5')

@agent.tool
def get_weather(city: str) -> str:
    return f"The weather in {city} is sunny"

app = agent.to_web()

logfire.instrument_fastapi(app, capture_headers=True)

# Run with: uvicorn app:app

testing

7 tests in tests/test_ui_web.py

notes

UI is served from CDN: @pydantic/[email protected]
Uses Vercel AI protocol for chat streaming
TODO: add clai web command to launch from the CLI (as in uvx pydantic-work without the whole URL magic)
TODO: should I add a new doc at docs/ui/to_web.md? I'd also reference this in docs/ui/overview.md and docs/agents.md

EDIT: if you try it out it's worth noting that the current hosted UI doesn't handle ErrorChunks, so you will get no spinner and no response when there's a model-level error and fastapi will return a 200 any way.
This will happen for instance when you use a model for which you don't have a valid API key in your environment
I opened a PR for the error chunks here pydantic/ai-chat-ui#4.

Closes #3295

pydantic_ai_slim/pydantic_ai/ui/web/app.py

clai/clai/chat/agent_discovery.py

DouweM · 2025-11-18T18:02:47Z

pydantic_ai_slim/pydantic_ai/_cli.py

    args = parser.parse_args(args_list)

+    # Handle web subcommand
+    if args.command == 'web':


Maybe it should be --web so it doesn't conflict with the prompt arg?

yeahp, changed that now

DouweM · 2025-11-18T18:03:24Z

pydantic_ai_slim/pydantic_ai/agent/__init__.py


        self._get_toolset().apply(_set_sampling_model)

+    def to_web(self) -> Any:


We're gonna need some args here -- have a look at the to_a2a and to_ag_ui methods. Not saying we need all of those args, but some may be useful

pydantic_ai_slim/pydantic_ai/agent/__init__.py

pydantic_ai_slim/pydantic_ai/ui/web/agent_options.py

pydantic_ai_slim/pydantic_ai/ui/web/app.py

tests/test_ui_web.py

dsfaccini · 2025-11-20T17:04:52Z

I just pushed an update to this removing the AST aspect and (hopefully) fixing the tests so they pass in CI

haven't addressed the comments yet so it isn't reviewable yet

- consolidate UI agent-options - fix cli commands - cache UI on client and server - offer choosable UI versions

- rename config vars to be nicer

pydantic_ai_slim/pydantic_ai/ui/web/agent_options.py

pydantic_ai_slim/pydantic_ai/ui/web/app.py

tests/test_agent_discovery.py

pydantic_ai_slim/pydantic_ai/_cli.py

tests/test_ui_web.py

clai/README.md

pydantic_ai_slim/pydantic_ai/ui/web/app.py

pydantic_ai_slim/pydantic_ai/ui/web/agent_options.py

dsfaccini · 2025-11-21T17:05:22Z

pydantic_ai_slim/pydantic_ai/_cli.py

    args = parser.parse_args(args_list)

+    # Handle web subcommand
+    if args.command == 'web':


yeahp, changed that now

clai/README.md

clai/clai/web/cli.py

DouweM · 2025-11-25T22:47:41Z

pydantic_ai_slim/pydantic_ai/ui/web/app.py

+
+    @app.get('/')
+    @app.get('/{id}')
+    async def index(request: Request, version: str | None = Query(None)):  # pyright: ignore[reportUnusedFunction]


I'm not sure I understand the need for a version arg. An older version than the default is worse, and a newer version may not work with the API data model. I think they should develop in tandem, with a pinned version on this side.

What we could do is add a frontend_url argument to the to_web method to allow the entire thing to be overridden easily?

frontend_url remains relevant, I haven't included logic for this

pydantic_ai_slim/pydantic_ai/ui/web/app.py

pydantic_ai_slim/pyproject.toml

test_agent.py

Regenerated uv.lock to resolve conflicts. 🤖 Generated with [Claude Code](https://claude.com/claude-code) Co-Authored-By: Claude <[email protected]>

…or starlette

- resolve model aliases - test builtin id type sync

clai/README.md

DouweM · 2025-12-02T18:08:14Z

clai/README.md

+
+- `--agent`, `-a`: Agent to serve in `module:variable` format
+- `--models`, `-m`: Comma-separated models to make available (e.g., `gpt-5,sonnet-4-5`)
+- `--tools`, `-t`: Comma-separated builtin tool IDs to enable (e.g., `web_search,code_execution`)


Link to builtin tools docs please. We may also need to list all the IDs as I don't think they're documented anywhere

Is "to enable" correct? Are they all enabled by default or just available as options?

most correctest would probably be offer or put at the disposal I guess, but enable seems good enough enable for the user

clai/README.md

pydantic_ai_slim/pydantic_ai/_cli/_web.py

DouweM · 2025-12-02T18:25:46Z

pydantic_ai_slim/pydantic_ai/_cli/_web.py

+            if tool_cls is None or tool_id in ('url_context', 'mcp_server'):
+                console.print(f'[yellow]Warning: Unknown tool "{tool_id}", skipping[/yellow]')
+                continue
+            if tool_id == 'memory':


I'd rather heave a constant set of unsupported builtin tool IDs, and then have a generic error X is not supported in the web UI because it requires configuration or something like that

pydantic_ai_slim/pydantic_ai/_cli/_web.py

DouweM · 2025-12-02T18:27:17Z

pydantic_ai_slim/pydantic_ai/agent/__init__.py

+        | None = None,
+        builtin_tools: list[AbstractBuiltinTool] | None = None,
+    ) -> Starlette:
+        """Create a Starlette app that serves a web chat UI for this agent.


I had a comment somewhere about exposing more starlette arguments like to_a2a and to_ag_ui do, can we do that please?

We should also support instructions, and any other options to run/iter that makes sense to override. Like model_settings etc. I believe to_ag_ui does that too

I took that comment to mean that we should be passing the models and builtin tools as args, since they were part of a config file before, I'm not sure otherwise what other options we should make available... do you have a link to an example?

@dsfaccini Essentially to_web wraps both agent.run and Starlette(), which both take many args people may want to tweak. So for example look at AbstractAgent.to_ag_ui

added settings and deps for now, the Starlette-specific args we discussed can be set externally, let's talk if there are any agent-specific ones that are missing here

DouweM · 2025-12-02T19:48:26Z

pydantic_ai_slim/pydantic_ai/models/__init__.py

+            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. '


If multiple tools are unsupported, we'd now get separate exceptions and only see the first. I'd rather have one exception that lists all the unsupported types. So we can do effectively if len(params.builtin_tools - self.profile.supported_builtin_tools) > 0 (with the correct types of course)

pydantic_ai_slim/pydantic_ai/models/__init__.py

pydantic_ai_slim/pydantic_ai/models/anthropic.py

pydantic_ai_slim/pydantic_ai/models/bedrock.py

pydantic_ai_slim/pydantic_ai/ui/_web/api.py

pydantic_ai_slim/pydantic_ai/ui/_web/app.py

pydantic_ai_slim/pydantic_ai/ui/_web/api.py

DouweM · 2025-12-02T20:15:47Z

pydantic_ai_slim/pydantic_ai/ui/_web/api.py

+def add_api_routes(
+    app: Starlette,
+    agent: Agent,
+    models: list[ModelInfo] | None = None,


The comment on line model=extra_data.model makes me thing we should be passing the raw model instance/names into this method, not the pre-processed ModelInfo. And we should generate the ModelInfo inside this method / inside the configure endpoint.

DouweM · 2025-12-02T20:17:08Z

pydantic_ai_slim/pydantic_ai/ui/_web/app.py

+
+    app = Starlette()
+
+    add_api_routes(


I think we can refactor this to return a Starlette router for just the API that can then be mounted into the main starlette app. that way it doesn't need to take app, and the API is more cleanly separate from the UI

Added link for web chat UI screenshot.

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

…o completion

dsfaccini · 2025-12-04T16:30:05Z

working on removing mcp support and the remaining 4 comments

- return routes instead of passing app into craete api routes - handle model instance resolution inside api route creator - update docs

DouweM · 2025-12-09T18:28:31Z

clai/README.md


 ```bash
-uvx clai
+uvx clai chat


Hmm can we keep clai working as it did, and not require this new argument?

we can, I though this would be cleaner/less confusing

DouweM · 2025-12-09T18:29:53Z

clai/README.md


+## Web Chat UI
+
+Launch a web-based chat interface for your agent:


Let's first have an example without an agent, to show that it will work that way as well

clai/README.md

DouweM · 2025-12-09T19:23:07Z

pydantic_ai_slim/pydantic_ai/builtin_tools.py

+# used in a couple places
+def get_builtin_tool_types() -> frozenset[type[AbstractBuiltinTool]]:
+    """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)


Instead of having this be a method that always returns the same thing, could this be a constant?

DouweM · 2025-12-09T19:23:50Z

pydantic_ai_slim/pydantic_ai/ui/_web/api.py

+    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


a few typos here!

DouweM · 2025-12-09T19:24:31Z

pydantic_ai_slim/pydantic_ai/ui/_web/api.py

+    agent: Agent[AgentDepsT, OutputDataT],
+    models: ModelsParam = None,
+    builtin_tools: Sequence[AbstractBuiltinTool] | None = None,
+    toolsets: Sequence[AbstractToolset[AgentDepsT]] | None = None,


We don't need to support this yet right? As we don't do MCP for now

DouweM · 2025-12-09T19:25:53Z

pydantic_ai_slim/pydantic_ai/ui/_web/api.py

+            model_id = model_ref if isinstance(model_ref, str) else f'{model.system}:{model.model_name}'
+            display_name = label or model.label
+            model_supported_tools = model.profile.supported_builtin_tools
+            supported_tool_ids = [t.kind for t in (model_supported_tools & builtin_tool_types)]


Shouldn't this also be t.unique_id? Or at least, I think those are the values that should show up in ModelInfo. Have you tested the entire feature with multiple MCPServerTools?

DouweM · 2025-12-09T19:30:55Z

pydantic_ai_slim/pydantic_ai/ui/_web/api.py

+    # Build model ID → original reference mapping and ModelInfo list for frontend
+    model_id_to_ref: dict[str, Model | str] = {}
+    model_infos: list[ModelInfo] = []
+    builtin_tools = builtin_tools or []


I mentioned above that we should not send agent._builtin_tools into this method, but what we should do is check if any of the provided new builtin_tools are already in agent._builtin_tools, so that we filter them out and don't show them in the UI as a checkbox, if they're hard-coded on the agent and are always going to be included anyway.

Co-authored-by: Douwe Maan <[email protected]>

add Agent.to_web() method and web chat UI module pydantic#3295

1cfa48e

dsfaccini commented Nov 17, 2025

View reviewed changes

pydantic_ai_slim/pydantic_ai/ui/web/app.py Outdated Show resolved Hide resolved

dsfaccini added 5 commits November 17, 2025 14:28

add "web" group

d83caa5

try import create_chat_app

bfffd4b

fix tests to run on CI

055e120

fix example to use tool_plain

6bc8b16

add clai web - tested with uv run clai web

32f7e1d

DouweM requested changes Nov 18, 2025

View reviewed changes

DouweM self-assigned this Nov 18, 2025

DouweM added the awaiting author revision label Nov 18, 2025

wip: remove agent discovery and fix tests

cf0e177

dsfaccini added 10 commits November 20, 2025 12:09

rename command

e7f44eb

rename function

c4ffde3

- define builtin tool ids

0595c27

- consolidate UI agent-options - fix cli commands - cache UI on client and server - offer choosable UI versions

fix tests

0d24941

- update CLI commands and improve agent loading mechanism

e5b30c2

- rename config vars to be nicer

Merge branch 'main' into clai-chat

f2dd19a

import sorting

8ca7a27

more import sorting

fa3bb5f

covergae?

e45c93f

Merge upstream/main into clai-chat

f90b570

dsfaccini commented Nov 25, 2025

View reviewed changes

DouweM requested changes Nov 25, 2025

View reviewed changes

dsfaccini and others added 6 commits November 26, 2025 09:22

Merge upstream/main into clai-chat

da8032c

Regenerated uv.lock to resolve conflicts. 🤖 Generated with [Claude Code](https://claude.com/claude-code) Co-Authored-By: Claude <[email protected]>

- remove agent_options - add supported_builtin_tools - swap fastapi f…

0ab07b6

…or starlette

refactor from --web to web, adjust flags, add tests, update docs

191897f

remove clai import on test

1faae3f

coverage

8423e89

- consolidate web docs in own doc

a32c15a

- resolve model aliases - test builtin id type sync

dsfaccini added 5 commits November 29, 2025 13:14

coverage

4b58307

add anthropic prefix

74f09e9

fix naming

897e4e4

remove get agent utility and make supported builtin tools a classmethod

10d32fe

remove test

1c93cf0

dsfaccini requested a review from DouweM December 1, 2025 18:12

DouweM requested changes Dec 2, 2025

View reviewed changes

Add screenshot link for web chat UI

b60f2ff

Added link for web chat UI screenshot.

dsfaccini mentioned this pull request Dec 3, 2025

Add MCP support to the Web UI #3635

Open

dsfaccini added 7 commits December 3, 2025 19:47

- remove builtin_tools suport check for specific models, base model t…

ee21cfb

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

support double instructions

cf1da90

remove program check, tie tool arg options to constant and set up aut…

372db8b

…o completion

merge

32cc5c5

add support for model instances, deps and settings

48094d2

fix tests after cli adjustments

cd1e683

separate chat command

c1ba780

dsfaccini force-pushed the clai-chat branch from 0e3cfc3 to c1ba780 Compare December 4, 2025 01:38

dsfaccini added 2 commits December 4, 2025 00:02

Merge branch 'main' into clai-chat

6984dfd

Merge branch 'main' into clai-chat

cf54985

dsfaccini added 4 commits December 4, 2025 12:53

- remove mcp support for now

106c8b9

- return routes instead of passing app into craete api routes - handle model instance resolution inside api route creator - update docs

Merge branch 'main' into clai-chat

f491e57

narrow types

16e36dc

Merge branch 'main' into clai-chat

48bd838

DouweM mentioned this pull request Dec 9, 2025

Let built-in tools fallback on custom tools for models that don't support them #3212

Open

DouweM requested changes Dec 9, 2025

View reviewed changes

dsfaccini and others added 3 commits December 9, 2025 14:45

Update clai/README.md

b45156c

Co-authored-by: Douwe Maan <[email protected]>

Merge branch 'main' into clai-chat

3733a56

Update clai/README.md

b57fb38

Co-authored-by: Douwe Maan <[email protected]>


		self._get_toolset().apply(_set_sampling_model)

		def to_web(self) -> Any:


		## Web Chat UI

		Launch a web-based chat interface for your agent:

Add Agent.to_web() method and web chat UI #3456

Are you sure you want to change the base?

Add Agent.to_web() method and web chat UI #3456

Uh oh!

Conversation

dsfaccini commented Nov 17, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

fastapi

options and example

testing

notes

Uh oh!

Uh oh!

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

dsfaccini commented Nov 20, 2025

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Uh oh!

dsfaccini commented Nov 17, 2025 •

edited

Loading