Mastering the Web UI in PydanticAI: Local Debugging Made Easy

Learn how to quickly set up and use the built-in Web Chat UI for local development and debugging with PydanticAI agents.

Posted on: 2026-03-01 by AI Assistant

Mastering the Web UI in PydanticAI

PydanticAI provides a built-in Web Chat UI that is incredibly useful for interacting with your agents during local development and debugging. While production environments should typically use more robust UI Event Stream integrations, the to_web() method offers a quick way to get a functional browser interface for your agents.

Why Use the Web UI?

The Web UI is designed for local development and debugging. It allows you to:

• Test agent prompts and tools in a real-world chat environment.
• Quickly switch between different models to compare results.
• Enable built-in tools like code execution and web search to see how they perform.

Getting Started

To use the web UI, you first need to install the web extra, which includes Starlette and Uvicorn:

pip install 'pydantic-ai-slim[web]'

Basic Implementation

Converting any Agent instance into a web application is as simple as calling the .to_web() method.

from pydantic_ai import Agent

# Initialize your agent
agent = Agent('openai:gpt-4o', instructions='You are a helpful assistant.')

# Add a tool
@agent.tool_plain
def get_weather(city: str) -> str:
    return f'The weather in {city} is sunny'

# Convert to a web application
app = agent.to_web()

Running Your Application

You can run the application using an ASGI server like Uvicorn:

uvicorn my_module:app --host 127.0.0.1 --port 7932

Advanced Configuration

The .to_web() method accepts several parameters to customize the UI experience:

1. Model Selection

Specify which models are available in the UI dropdown:

app = agent.to_web(
    models={'GPT 4o': 'openai:gpt-4o', 'Claude': 'anthropic:claude-3-5-sonnet-latest'},
)

2. Enabling Built-in Tools

Enable powerful tools like the CodeExecutionTool or WebSearchTool directly through the web interface:

from pydantic_ai.builtin_tools import CodeExecutionTool, WebSearchTool

app = agent.to_web(builtin_tools=[CodeExecutionTool(), WebSearchTool()])

3. Extra Instructions

Add instructions specific to the web interface runs without modifying the core agent:

app = agent.to_web(instructions='Always respond in a friendly tone.')

4. Custom HTML Source

For offline usage, you can point to a local HTML file:

app = agent.to_web(html_source='~/pydantic-ai-ui.html')

Important Considerations

• Reserved Routes: The application uses several reserved routes at the root level (/, /api/chat, /api/configure, and /api/health). Avoid overwriting these.
• Subpaths: Currently, the app cannot be mounted at a subpath (e.g., /chat) because the UI expects routes at the root.
• Memory Tool: The memory built-in tool is not supported via to_web(). If you need memory, configure MemoryTool directly on the agent during construction.

By leveraging the PydanticAI Web UI, you can significantly speed up your development cycle and gain better insights into how your agents interact with tools and models.