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

dsfaccini · 2025-11-29T04:45:36Z

been having some fun testing the combinations, for anyone who wants to try them:

combinations to try out the agent UI

1. Generic agent with explicit model

source .env && uv run --with . clai web -m openai:gpt-4.1-mini

2. Agent with model (uses agent's configured model)

source .env && uv run --with . clai web -a clai.clai._test_agents:chat_agent

3. Agent without model + CLI model

source .env && uv run --with . clai web -a clai.clai._test_agents:agent_no_model -m anthropic:claude-haiku-4-5

4. Multiple models (first is default, others are options in UI)

source .env && uv run --with . clai web -m google-gla:gemini-2.5-flash-lite -m openai:gpt-4.1-mini -m anthropic:claude-haiku-4-5

5. Override agent's model with different one

source .env && uv run --with . clai web -a clai.clai._test_agents:chat_agent -m google-gla:gemini-2.5-flash-lite

6. Single tool - web search enabled

source .env && uv run --with . clai web -m openai:gpt-4.1-mini -t web_search

7. Multiple tools

source .env && uv run --with . clai web -m anthropic:claude-haiku-4-5 -t web_search -t code_execution

8. Agent with builtin_tools configured

source .env && uv run --with . clai web -a clai.clai._test_agents:agent_with_tools

9. Roleplay waiter instructions

source .env && uv run --with . clai web -m openai:gpt-4.1-mini -i "You're a grumpy Parisian waiter at a trendy bistro frequented by American tourists. You're secretly proud of the food but act annoyed by every question. Pepper your
responses with French words and sighs."

10. With MCP config

source .env && uv run --with . clai web -m google-gla:gemini-2.5-flash-lite --mcp mcp_servers.json

11. ERROR: No model, no agent (should error)

source .env && uv run --with . clai web

12. ERROR: Agent without model, no CLI model (should error)

source .env && uv run --with . clai web -a clai.clai._test_agents:agent_no_model

13. WARNING: Unknown tool (should warn)

source .env && uv run --with . clai web -m openai:gpt-4.1-mini -t definitely_not_a_real_tool

Some fun alternative instructions you could swap in for #9:

Pirate customer service

source .env && uv run --with . clai web -m anthropic:claude-haiku-4-5 -i "You're a pirate who somehow ended up working tech support. Answer questions helpfully but can't stop using nautical terms and saying 'arrr'."

Overly enthusiastic fitness coach

source .env && uv run --with . clai web -m google-gla:gemini-2.5-flash-lite -i "You're an extremely enthusiastic fitness coach who relates EVERYTHING back to exercise and healthy living. Even coding questions get workout analogies."

Noir detective

source .env && uv run --with . clai web -m openai:gpt-4.1-mini -i "You're a 1940s noir detective narrating your investigation. Every question is a 'case' and every answer is delivered in hard-boiled prose with lots of rain metaphors."

.env.example

export ANTHROPIC_API_KEY=""
export OPENAI_API_KEY=""
export GOOGLE_API_KEY=""

When we publish it should naturally just run as uvx clai web ..., we could support a --url to fetch the agent code from, that would make it easier to publish examples. Though that sounds a bit dangerous as well.

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

DouweM · 2025-12-02T18:13:11Z

clai/README.md


 ```
-usage: clai [-h] [-m [MODEL]] [-a AGENT] [-l] [-t [CODE_THEME]] [--no-stream] [--version] [prompt]
+usage: clai [-h] [-m [MODEL]] [-a AGENT] [-l] [-t [CODE_THEME]] [--no-stream] [--version] [prompt] {web} ...


This is the real help output right? We should be able to get things to render such that web is clearly a subcommand with its own options, right now it looks like it's a "web" word at the end of the regular command.

that's how it shows

DouweM · 2025-12-02T18:24:47Z

pydantic_ai_slim/pydantic_ai/_cli/_web.py

+    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'):


We shouldn't have magic values like this inline; these should be a constant

you're right, replaced with a constant

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

pydantic_ai_slim/pydantic_ai/_cli/_web.py

+        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]')


Let's have a separate error for mcp_server like for memory below

yeah. made a reusable error, lists all errors

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

DouweM · 2025-12-02T19:49:31Z

pydantic_ai_slim/pydantic_ai/models/__init__.py

+        return _format_model_label(self.model_name)
+
+    @classmethod
+    def supported_builtin_tools(cls) -> frozenset[type[AbstractBuiltinTool]]:


Can this be a property? Assuming a class property is a thing

nope, properties need "The Self"

pydantic_ai_slim/pydantic_ai/models/anthropic.py

DouweM · 2025-12-02T19:50:58Z

pydantic_ai_slim/pydantic_ai/models/bedrock.py


-        if model_request_parameters.builtin_tools:
+        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


Let's remove it like we did for Cohere

DouweM · 2025-12-02T20:11:36Z

pydantic_ai_slim/pydantic_ai/ui/_web/api.py

+            agent=agent,
+            model=extra_data.model,
+            builtin_tools=request_builtin_tools,
+            toolsets=_toolsets,


I'm starting to think that maybe --mcp doesn't make sense as we've currently implemented it, as they are always included instead of being selectable like the builtin tools... For consistency, either both should always be on, both should be optional, or it should be configurable which are enabled by default and which are optional, but the current behavior is confusingly inconsistent.

Of course that wasn't an issue when we used MCPServerTool before, but I thought that was too limiting as it requied on provider support when we don't really have to.

From a product perspective, I think we should make the MCP servers selectable as well, but I don't want to wait to get that ready before we ship this, as we'd need to update the frontend (i.e. not use the builtinTools key? have a new key for tools that do not rely on model support?). I think it's best to split that out for now, and create a new followup PR.

In general smaller PRs with incremental improvements are better than dumping a huge feature in one go, so I'd rather ship what's ready now, and then do the rest later.

noted, will remove mcp support for now

pydantic_ai_slim/pydantic_ai/ui/_web/app.py

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

pydantic_ai_slim/pydantic_ai/ui/_web/api.py

+        streaming_response = await VercelAIAdapter.dispatch_request(
+            request,
+            agent=agent,
+            model=extra_data.model,


If a model instance was provided, we should use it instead of passing in the ID directly! We need to have a map of model IDs to the original thing that was provided (model instance or name)

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

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 2 commits November 29, 2025 11:58

move builtin tool support to profile and move check to base model class

40b5c78

fix test profile classes to avoid ci api key error

0673277

dsfaccini force-pushed the clai-chat branch from 08a48d8 to 0673277 Compare November 29, 2025 17:33

dsfaccini added 6 commits November 29, 2025 12:48

Merge branch 'main' into clai-chat

974bac2

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


		self._get_toolset().apply(_set_sampling_model)

		def to_web(self) -> Any:

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

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!

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

Uh oh!

1. Generic agent with explicit model

2. Agent with model (uses agent's configured model)

3. Agent without model + CLI model

4. Multiple models (first is default, others are options in UI)

5. Override agent's model with different one

6. Single tool - web search enabled

7. Multiple tools

8. Agent with builtin_tools configured

9. Roleplay waiter instructions

10. With MCP config

11. ERROR: No model, no agent (should error)

12. ERROR: Agent without model, no CLI model (should error)

13. WARNING: Unknown tool (should warn)

Pirate customer service

Overly enthusiastic fitness coach

Noir detective

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!

Choose a reason for hiding this comment

dsfaccini commented Nov 17, 2025 •

edited

Loading

dsfaccini commented Nov 29, 2025 •

edited

Loading