Quickstart¶
Five minutes, no API key. You will play a demo, draw the blueprint of an agent from its source code without running it, and watch a run live.
Install¶
It needs Python 3.11 or newer. Its only direct dependencies are pydantic-ai-slim and opentelemetry-sdk, so it adds no model provider and no web framework to your project.
1. Play the demo¶
A browser tab opens and a scripted support agent starts working on a ticket. Watch for:
- tokens streaming into the model request,
- three tool calls running in parallel,
- one tool turning amber (it asked the model to retry) and then succeeding,
- a dashed edge to a second agent turning solid when the delegation actually happens,
- the output node lighting up when the run ends.
Click any row in the timeline to inspect it. Drag the scrubber, or press Space, to replay. Press ? for all keyboard shortcuts.
pydantic-ai-viz demo --list shows the other demos; see Demos. Stop the server with Ctrl+C.
2. Draw the blueprint of an agent, without running it¶
Save this as quickstart.py. It uses Pydantic AI's TestModel, so it also runs offline in step 3:
from pydantic_ai import Agent
from pydantic_ai.models.test import TestModel
agent = Agent(TestModel(), name="helper", instructions="Answer briefly.")
@agent.tool_plain
def add(a: int, b: int) -> int:
"""Add two numbers."""
return a + b
if __name__ == "__main__":
print(agent.run_sync("What is 2 + 3?").output)
Then:
The viewer shows the helper agent, its model, the add tool with its parameter schema and the description from its docstring, and a text output, each with the line of quickstart.py it is defined at. view reads the source and stops there: the file is not imported and none of it runs, so no agent is run, no model is called, and nothing it imports has to be installed.
Now point it at your own code. A directory is read whole, and imports between its files are followed, so a tool or an output model defined in another file is drawn with the agent that uses it:
pydantic-ai-viz view my_app/ # every .py file below my_app
pydantic-ai-viz view my_app/agents.py:support_agent # one agent, and the agents it delegates to
Where the code computes a value when it runs, for example Agent(os.getenv("MODEL")), the viewer shows that expression marked "decided at run time" rather than a guess. More in Visualize an agent, and in How view works.
3. Watch a run live¶
Without changing your code¶
run starts the viewer, runs your script as python quickstart.py would, and keeps serving after the script ends so you can look around. Every agent run in the script appears as it happens.
From your code¶
import pydantic_ai_viz as pviz
from quickstart import agent
with pviz.serve(agent, open_browser=True) as session:
agent.run_sync("What is 2 + 3?")
session.wait() # block until Ctrl+C so the viewer stays up
serve starts a local server on http://127.0.0.1:8765 and captures every agent run in this process from then on. The agent you pass is drawn at once; other agents show up when they first run. The calls to your agent stay exactly as they were.
More in Watch live runs.
4. Keep a run¶
Use record when you want the file and not a server:
import pydantic_ai_viz as pviz
from quickstart import agent
with pviz.record(agent) as session:
agent.run_sync("What is 2 + 3?")
session.save("helper.pviz.jsonl") # a recording: replay it with `pydantic-ai-viz open`
session.export_html("helper.html") # an export: one HTML file, opens offline
Exports contain your data
A recording or an export holds the prompts, tool arguments and tool results of the run in plain text. Read Privacy before you share one.
Where next¶
- Running against a real model works the same way; nothing here is specific to
TestModel. - Token streaming shows tokens as they arrive. It is opt-in for a reason.
- Graphs covers
pydantic-graph. - Already using Logfire? Read Use with Logfire first.
- If no runs appear, see Troubleshooting.