Add Agent.to_web() method and web chat UI

[dsfaccini]

web-based chat interface for Pydantic AI agents

1. new module pydantic_ai.ui.web
2. 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

[DouweM]

This is cool but I think it's too much magic, at least for the first version of this feature (I wouldn't throw the code away; we could consider it as a separate PR later). I think the existing -a AGENT flag is sufficient for now.

[DouweM]

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

[DouweM]

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

[DouweM]

The is that the UI would be downloaded and cached on first use, so it's not meant to always be "served from a CDN"

[DouweM]

The goal is for the developer to be able to pass a list of models and builtin tools to to_web, instead of anything hard-coded they may not have keys for. We'd need a new field like supported_builtin_tools on ModelProfile to store for each model/provider which builtin tools it supports. Then we can automatically generate the structures below based on the user-provided data and which tools work with which models.

[DouweM]

Friendly names for builtin tools can go in builtin_tools.py

[DouweM]

I think we should pin a specific version, in case we make backward-incompatible changes at some point

[DouweM]

We should cache this somewhere

[DouweM]

Use a snapshot please :)