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

clai/clai/web/cli.py

pydantic_ai_slim/pydantic_ai/builtin_tools.py

pydantic_ai_slim/pydantic_ai/ui/_web/api.py

pydantic_ai_slim/pydantic_ai/ui/web/app.py

dsfaccini · 2025-11-27T16:07:17Z

tests/test_ui_web.py

+    with TestClient(app) as client:
+        response = client.get('/')
+        assert response.status_code == 200
+        assert response.headers['content-type'] == 'text/html; charset=utf-8'
+        assert 'cache-control' in response.headers
+        assert response.headers['cache-control'] == 'public, max-age=3600'
+        assert len(response.content) > 0


this can stay as assertions right?

clai/clai/web/cli.py

pydantic_ai_slim/pydantic_ai/ui/web/app.py

DouweM · 2025-11-27T19:06:35Z

pydantic_ai_slim/pydantic_ai/ui/web/app.py

+        model_id = f'{model.system}:{model.model_name}'
+        display_name = label or format_model_display_name(model.model_name)
+        model_supported_tools = model.supported_builtin_tools()
+        supported_tool_ids = list(model_supported_tools & builtin_tool_ids)


I think I suggested putting this in Model.profile so that we can always trust model.profile.supported_builtin_tools. Then we can also override it on OpenAIChatModel to remove web_search if appropriate

pydantic_ai_slim/pydantic_ai/ui/web/app.py

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.

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 27, 2025 11:05

remove memory cache and swap prints for consoles

91f9533

use snapshots where it makes sense

441d6a0

dsfaccini commented Nov 27, 2025

View reviewed changes

Merge branch 'main' into clai-chat

558985f

dsfaccini requested a review from DouweM November 27, 2025 16:17

DouweM requested changes Nov 27, 2025

View reviewed changes

dsfaccini added 8 commits November 28, 2025 15:52

make _web a private module

85f63bc

move supported_builtin_tools to abstract tool set type

cd91e81

warning about memory tool

a132f26

move name formatting to model method

943c7a8

move to toolsets

831bdf3

update docstring

125c059

take agent's own model into account

025f1b5

bit of docs

0701b22

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

Merge branch 'main' into clai-chat

974bac2


		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!

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!

Uh oh!

Uh oh!

Uh oh!

Choose a reason for hiding this comment

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

dsfaccini commented Nov 17, 2025 •

edited

Loading

dsfaccini commented Nov 29, 2025 •

edited

Loading