Skip to content

Python API

Everything public is importable from the top-level package. The examples in these docs use the alias pviz:

import pydantic_ai_viz as pviz
Name Use it to
serve Capture runs and show them live in a browser
record Capture runs without a server, to save or inspect them
analyze Read agents and graphs out of source files, without importing or running them
blueprint Get the structure of a live agent or graph as data
export_html Write a single-file HTML export
run_graph Run a pydantic-graph graph so its nodes are captured
Session The object serve and record return
AgentBlueprint, GraphBlueprint The models blueprint and analyze return
Analysis, Limits What analyze returns, and the bounds on its work
__version__ The installed version, as a string

Names that start with an underscore, and modules other than pydantic_ai_viz itself, are internal and can change in any release.

A target is something to draw: an Agent, a Graph, a module whose top-level agents and graphs should all be drawn, or an Analysis of source files.

Target = Agent[Any, Any] | Graph[Any, Any, Any, Any] | ModuleType | Analysis

serve

def serve(
    *targets: Target,
    host: str = "127.0.0.1",
    port: int = 8765,
    open_browser: bool = False,
    include_content: bool = True,
    stream: bool = False,
    instrument: bool = True,
    title: str | None = None,
    max_events: int = 50_000,
) -> Session

Start a session, start the local viewer server in a background thread, and return at once.

with pviz.serve(agent, open_browser=True) as session:
    agent.run_sync("Where is my order?")
    session.wait()
Parameter Meaning
*targets Agents, graphs and modules to draw before any run. Capture covers every agent in the process whether or not it is listed.
host Address to bind. A non-loopback address issues a UserWarning and exposes the session to the network without authentication.
port Port to bind. If it is busy, a free port is used instead. 0 always picks a free port. The real address is session.url.
open_browser Open the viewer in the default browser.
include_content Capture prompts, instructions, tool arguments, tool results and outputs. False captures structure, timing and token counts only. Applies when instrument=True.
stream Capture tokens as they arrive. This switches the agents' model requests to streaming; see Token streaming. Has no effect with include_content=False, because tokens are content.
instrument True: call Agent.instrument_all(...) with a private tracer provider, and set PYDANTIC_AI_NO_BANNER=1 unless it is set, because Pydantic AI's banner would report observability as off. False: touch nothing global; you add session.span_processor to your own provider. See Use with Logfire.
title Session title, shown in the viewer and used for download file names.
max_events Upper bound on the in-memory event log. Past it, the oldest finished runs are dropped whole.

Raises

  • RuntimeError("a pydantic-ai-viz session is already active; close it first") if another instrumenting session is active.
  • TypeError if a target is not an agent, a graph, a module or an Analysis.
  • OSError if the server cannot bind host at all.

Guide: Watch live runs.

record

def record(
    *targets: Target,
    include_content: bool = True,
    stream: bool = False,
    instrument: bool = True,
    title: str | None = None,
    max_events: int = 50_000,
) -> Session

Like serve, but with no server: session.url is None. Use it in scripts, notebooks and tests, then read session.events, or call session.save(...) or session.export_html(...).

with pviz.record(agent) as session:
    agent.run_sync("Where is my order?")
    session.save("run.pviz.jsonl")

The parameters mean the same as for serve, and the same rule applies: one instrumenting session at a time (RuntimeError). Sessions opened with instrument=False are not limited. A target of the wrong kind raises TypeError.

Guide: Export and share.

analyze

def analyze(
    *targets: str | os.PathLike[str],
    limits: Limits | None = None,
) -> Analysis

Describe the agents and graphs in Python source files without importing or running them. The files are parsed: nothing they import has to be installed, no model is called and none of their code runs. This is what pydantic-ai-viz view does.

found = pviz.analyze("my_app/agents.py")
for agent in found.agents:
    print(agent.label, agent.location, [tool.name for tool in agent.tools])
    print(agent.warnings)  # what the source computes at run time

pviz.export_html(found, "blueprint.html")
Parameter Meaning
*targets What to read, each one of: the path of a .py file; the path of a directory, whose .py files are all read, however deep; a module name such as "my_app.agents", found on disk without importing anything; or a GitHub repository, as "https://github.com/owner/repo[/tree/REF[/SUBDIR]]" or "gh:owner/repo[@REF][/SUBDIR]", fetched with git and only read. "path/to/file.py:name" and "my_app.agents:name" select the agent or graph assigned to name at the top level of that file, together with the agents it delegates to. The command line reference describes each form.
limits A Limits; the defaults suit ordinary projects.

What the source spells out is reported as a value. What it computes at run time, such as Agent(get_model()), is reported as the source text that computes it and named in the blueprint's warnings; nothing is guessed. A file that cannot be read or parsed is skipped and named in Analysis.notices.

Imports between the project's own files are followed, so a tool, an output model, a toolset or a delegate defined in another file is described from that file. A file that is read only because another one imports it adds no blueprints of its own, except for the agents and graphs that a target's file knows by name and the agents those delegate to. Installed packages are never opened, except the source of the installed Pydantic AI, for the tools it defines.

Raises ValueError if a target does not exist, cannot be fetched, or selects a name that no agent or graph is assigned to.

The result can be passed to export_html, serve, record and Session.register like any other target. Runs of an agent are then drawn on the blueprint read from source that carries its name.

Concept: How view works.

Analysis

@dataclass(frozen=True)
class Analysis:
    agents: list[AgentBlueprint]
    graphs: list[GraphBlueprint]
    notices: list[str]
    files: list[str]
    title: str | None

    @property
    def blueprints(self) -> list[AgentBlueprint | GraphBlueprint]: ...
Field Meaning
agents One blueprint per Agent(...) in the source, with ids a1, a2, ... in the order they appear. delegates refer to these ids.
graphs One blueprint per GraphBuilder(...) or Graph(nodes=[...]), with ids g1, g2, ...
notices Messages about the analysis as a whole: a file that was skipped because it is not valid Python, the commit a GitHub repository was read at, or how many tools were found that belong to no agent the source shows.
files The files that were read, relative to the directory of the targets (for a GitHub repository, to the top of the repository): the targets' own files first, then the files read because those import them, which start with ../ when they lie outside that directory. Targets that share no directory, such as a GitHub repository and a local file, have their files named under a label each: owner/repo@abc1234/..., or the name of the target's project directory.
title A short name for what was analysed: the file, directory or module, or owner/repo@commit. None when there were several targets.
blueprints The agents, then the graphs.

Every blueprint from analyze has source == "code" and a location (file and line).

Limits

@dataclass(frozen=True)
class Limits:
    max_file_bytes: int = 2_000_000
    max_files: int = 2_000
    max_seconds: float = 30.0
    max_fetch_seconds: float = 300.0

Bounds that keep the analysis of unknown code quick and finite. A file larger than max_file_bytes is skipped, no more than max_files files are read, and the analysis stops once max_seconds have passed. Each of these leaves a notice. Fetching a GitHub repository is timed separately: it is given up, with a ValueError, after max_fetch_seconds.

blueprint

def blueprint(
    target: Agent[Any, Any] | Graph[Any, Any, Any, Any],
) -> AgentBlueprint | GraphBlueprint

Return the structure of a live agent or graph object. (To read source files without importing them, use analyze.) This is a pure function: it makes no model call, starts no server and needs no session. It works on an agent whose model is a string that cannot be resolved here (defer_model_check=True) and on an agent with no model at all.

bp = pviz.blueprint(agent)
print([tool.name for tool in bp.tools])
print(bp.warnings)

Anything that could not be read is reported in bp.warnings; the function does not raise for it.

Guide: Visualize an agent.

export_html

def export_html(
    source: Session | Agent[Any, Any] | Graph[Any, Any, Any, Any] | Analysis | str | os.PathLike[str],
    path: str | os.PathLike[str],
) -> Path

Write a self-contained HTML export to path and return the path.

source The export contains
A Session Everything the session has captured so far
A path to a .pviz.jsonl recording That recording
An Agent or a Graph Its blueprint only, with no runs
An Analysis The blueprints read from source, with no runs
pviz.export_html("run.pviz.jsonl", "run.html")
pviz.export_html(agent, "blueprint.html")
pviz.export_html(pviz.analyze("agents.py"), "blueprint.html")

run_graph

async def run_graph(
    graph: Graph[Any, Any, Any, Any],
    *,
    state: Any = None,
    deps: Any = None,
    inputs: Any = None,
    session: Session | None = None,
) -> Any

Run a graph and capture it: one graph_run span around the execution and one graph_node span per task. Returns the graph's output, as graph.run(...) would.

The session used is session if given, else the active session. With neither, the graph is run with graph.run(state=state, deps=deps, inputs=inputs) and nothing is captured, so the call is safe to leave in production code. The graph is registered with the session if it was not already.

An exception raised by the graph marks the graph run as an error and is re-raised unchanged.

output = await pviz.run_graph(graph, state=Draft(), inputs="Announce dark mode")

Guide: Graphs, including the limit for parallel steps.

Session

The object returned by serve and record. It owns the event log. A session is a context manager; leaving the with block calls close().

class Session:
    url: str | None
    title: str
    session_id: str
    mode: Literal["capture", "blueprint"]
    include_content: bool
    stream: bool

    @property
    def events(self) -> list[dict[str, Any]]: ...
    @property
    def span_processor(self) -> SpanProcessor: ...
    @property
    def closed(self) -> bool: ...

    def register(self, *targets: Target) -> None: ...
    def save(self, path: str | os.PathLike[str]) -> Path: ...
    def export_html(self, path: str | os.PathLike[str]) -> Path: ...
    def wait(self) -> None: ...
    def close(self) -> None: ...
Member Description
url Address of the viewer, for example "http://127.0.0.1:8765". None for a session from record.
title The session title. Without a title argument, the name of the first named target, or "pydantic-ai-viz".
session_id 32 hexadecimal characters, new for every session. It is the session_id of the session.started event.
mode "capture" for a session from serve or record, where runs can appear; "blueprint" for one that only ever holds blueprints, such as view's.
include_content, stream What the session captures. stream is False whenever include_content is False.
events A snapshot of the event log: a new list of JSON-ready dictionaries, one per event, in order. Still readable after close(). Treat the dictionaries as read-only. The shapes are in the wire format.
span_processor An OpenTelemetry SpanProcessor that feeds this session. Only needed with instrument=False: add it to your own tracer provider.
register(*targets) Draw more agents, graphs or modules. An agent's delegates, as far as its code shows, are registered with it. A module contributes its top-level agents and graphs, labelled by variable name when they have no name. Registering an object twice does nothing.
save(path) Write the event log as a .pviz.jsonl recording. Returns the path.
export_html(path) Write the event log as a single-file HTML export. Returns the path.
wait() Block until Ctrl+C, or until the session is closed from another thread. Use it to keep a script alive while you look at the viewer.
close() Stop the server and end the session. Safe to call more than once. If the session installed its instrumentation setting, the setting that was there before is put back (off, if there was none).
closed True once close() has run.

AgentBlueprint

A Pydantic model describing one agent. Returned by blueprint for an Agent, and carried by blueprint.agent events.

bp = pviz.blueprint(agent)
bp.model_dump()  # a plain dict
bp.model_dump_json()  # JSON, the same shape as on the wire

Main fields: id, name, label, description, source, location, model, deps_type, instructions, toolsets, tools, native_tools, output, capabilities, settings, delegates and warnings. Each is specified under Blueprints in the wire format reference.

GraphBlueprint

A Pydantic model describing one graph. Returned by blueprint for a Graph, and carried by blueprint.graph events.

Fields: id, name, label, source, location, state_type, input_type, output_type, nodes, edges, mermaid and warnings. See Blueprints.

Docstrings

The section below is generated from the docstrings of the installed source.

pydantic_ai_viz

pydantic-ai-viz: see what your Pydantic AI agents are and what they do.

Unofficial community project, not affiliated with or endorsed by Pydantic.

The whole public API is importable from here:

  • serve captures runs and shows them live in a local viewer.
  • record captures runs without a server.
  • analyze reads agents and graphs out of source files, without importing them.
  • blueprint describes a live agent or graph as data, without running it.
  • export_html writes a single-file HTML export.
  • run_graph runs a pydantic-graph Graph so its nodes are captured.
  • Session is what serve and record return.
  • AgentBlueprint and GraphBlueprint are the models blueprint returns.
  • Analysis is what analyze returns; Limits bounds its work.

Analysis dataclass

Analysis(
    agents: list[AgentBlueprint] = list[AgentBlueprint](),
    graphs: list[GraphBlueprint] = list[GraphBlueprint](),
    notices: list[str] = list[str](),
    files: list[str] = list[str](),
    title: str | None = None,
)

What analyze found.

Attributes:

Name Type Description
agents list[AgentBlueprint]

One blueprint per Agent(...) construction, with ids a1, a2, ... in the order they appear. delegates refer to these ids.

graphs list[GraphBlueprint]

One blueprint per GraphBuilder(...) or Graph(nodes=[...]), with ids g1, g2, ...

notices list[str]

Messages about the analysis as a whole, such as a file that was skipped because it is not valid Python, or the commit a GitHub repository was read at.

files list[str]

The files that were read, relative to the directory of the targets (for a GitHub repository, to the top of the repository): the targets' own files first, then the files read because those import them, which start with ../ when they lie outside that directory. Targets that share no directory, such as a GitHub repository and a local file, have their files named under a label each: owner/repo@abc1234/..., or the name of the target's project directory. A path is never absolute.

title str | None

A short name for what was analysed: the file, directory or module, or owner/repo@commit. None when there were several targets.

blueprints property
blueprints: list[AgentBlueprint | GraphBlueprint]

Every blueprint: the agents, then the graphs.

Limits dataclass

Limits(
    max_file_bytes: int = 2000000,
    max_files: int = 2000,
    max_seconds: float = 30.0,
    max_fetch_seconds: float = 300.0,
)

Bounds that keep the analysis of unknown code quick and finite.

max_file_bytes class-attribute instance-attribute
max_file_bytes: int = 2000000

A larger file is skipped, with a notice.

max_files class-attribute instance-attribute
max_files: int = 2000

No more files than this are read in one analysis.

max_seconds class-attribute instance-attribute
max_seconds: float = 30.0

Reading stops, with a notice, once this much time has passed. Fetching is timed separately.

max_fetch_seconds class-attribute instance-attribute
max_fetch_seconds: float = 300.0

How long fetching one GitHub repository may take before it is given up.

AgentBlueprint

Bases: WireModel

Structure of one agent, read from code, from a live object, or from its runs.

GraphBlueprint

Bases: WireModel

Structure of one pydantic-graph Graph, read from code or from a live object.

Session

Session(
    *,
    title: str | None = None,
    include_content: bool = True,
    stream: bool = False,
    instrument: bool = True,
    max_events: int = DEFAULT_MAX_EVENTS,
    mode: SessionMode = "capture",
    notices: Sequence[str] = (),
)

A capture session: registered blueprints plus every run observed while it is open.

Create one with record() (capture only) or serve() (capture plus the local viewer). A session is a context manager; leaving the block calls close().

Attributes:

Name Type Description
url str | None

Address of the local viewer, or None when there is no server.

title

Shown in the viewer's top bar and used for export file names.

session_id

32 hexadecimal characters, new for every session.

mode SessionMode

"capture" when runs can appear in the session, "blueprint" when it only ever holds blueprints.

include_content

Whether prompts, tool arguments and results are captured.

stream

Whether token deltas are captured. Always False when include_content is False: a token delta is content.

Open a session. Prefer record() or serve(), which also register targets.

Parameters:

Name Type Description Default
title str | None

Session title; defaults to "pydantic-ai-viz".

None
include_content bool

Capture prompts, tool arguments and results.

True
stream bool

Capture token deltas (switches model requests to streaming). Has no effect when include_content is false.

False
instrument bool

Call Agent.instrument_all with this session's tracer provider.

True
max_events int

Size of the event log before whole completed runs are dropped.

DEFAULT_MAX_EVENTS
mode SessionMode

"capture" for a session that records runs. "blueprint" tells the viewer that no run will ever appear, so it shows structure only; it requires instrument=False.

'capture'
notices Sequence[str]

Messages about the session as a whole, shown by the viewer.

()

Raises:

Type Description
RuntimeError

If instrument is true and another instrumenting session is open.

ValueError

If mode is "blueprint" and instrument is true.

events property
events: list[dict[str, Any]]

A snapshot of the event log: JSON-ready envelopes, oldest first.

The list is new on every access; the envelopes in it are the log's own and must be treated as read-only.

span_processor property
span_processor: SpanProcessor

The processor that feeds this session.

Only needed with instrument=False: add it to your own tracer provider, for example logfire.configure(additional_span_processors=[session.span_processor]).

closed property
closed: bool

True once close() has run.

register
register(*targets: Target) -> None

Add blueprints for agents, graphs, every agent and graph in a module, or an Analysis.

Agents that a registered agent's tools refer to are registered too. An Analysis (the result of analyze()) adds the blueprints it read from source; runs of an agent with the same name are then drawn on them. Registering the same object again does nothing.

Raises:

Type Description
TypeError

If a target is not an Agent, a Graph, a module or an Analysis.

save
save(path: str | PathLike[str]) -> Path

Write everything captured so far as a .pviz.jsonl recording.

A recording is the event log, one JSON event per line. Open it later with pydantic-ai-viz open, or turn it into a page with export_html(). It contains every captured prompt and tool result.

Parameters:

Name Type Description Default
path str | PathLike[str]

Where to write the file. An existing file is replaced.

required

Returns:

Type Description
Path

The path written.

Raises:

Type Description
OSError

If the file cannot be written.

export_html
export_html(path: str | PathLike[str]) -> Path

Write everything captured so far as one self-contained HTML file.

The file holds the viewer and the events and opens in any browser, with no server. It contains every captured prompt and tool result.

Parameters:

Name Type Description Default
path str | PathLike[str]

Where to write the file. An existing file is replaced.

required

Returns:

Type Description
Path

The path written.

Raises:

Type Description
OSError

If the file cannot be written.

wait
wait() -> None

Block until Ctrl+C, to keep a script alive while you look at the viewer.

Returns quietly on Ctrl+C, and also once close() is called from another thread. The session is left open; close it yourself or use a with block.

close
close() -> None

End the session: stop the server, stop capturing and undo Agent.instrument_all.

Safe to call twice. The events stay readable, so save() and export_html() still work. Runs still in flight finish normally; what they emit after this point is not recorded.

analyze

analyze(
    *targets: str | PathLike[str],
    limits: Limits | None = None,
) -> Analysis

Describe the agents and graphs in Python source code, without importing or running it.

The files are parsed, not executed: nothing they import has to be installed, no model is called and no code of theirs runs. What the source spells out is reported as a value; what it computes at run time is reported as the source text that computes it, and listed in the blueprint's warnings.

import pydantic_ai_viz as pviz

found = pviz.analyze("src/my_app")
for agent in found.agents:
    print(agent.label, [tool.name for tool in agent.tools])
pviz.export_html(found, "blueprint.html")

A target is one of:

  • A file, path/to/file.py. path/to/file.py:name selects the agent or graph assigned to name at the top level of that file.
  • A directory. Every .py file below it is read. Virtual environments, node_modules, site-packages, __pycache__, build, dist and hidden directories are passed over; a build or dist that holds .py files is named in a notice.
  • A module name, package.module or package.module:name. The file is found on disk, below the working directory, its src directory or an entry of sys.path; nothing is imported to find it. A package is read like a directory.
  • A GitHub repository, https://github.com/owner/repo, optionally followed by /tree/<ref>/<subdir> or /blob/<ref>/<file>, or in short gh:owner/repo[@ref][/subdir]. A ref is a branch, a tag or a full commit SHA. The commit is fetched with git into a cache directory and only read.

Imports between the project's own files are followed, so an agent, a tool, an output model or a delegate defined in another file is described from that file. A file that is read only because another one imports it adds no blueprints of its own, except for the agents and graphs a target's file knows by name and the agents those delegate to. Installed packages are never opened, except the source of the installed Pydantic AI, for the tools it defines.

Parameters:

Name Type Description Default
*targets str | PathLike[str]

Files, directories, module names or GitHub repositories, as above.

()
limits Limits | None

Bounds on file size, file count and time; the defaults suit ordinary projects.

None

Returns:

Type Description
Analysis

The blueprints found, plus notices about anything that had to be skipped.

Analysis

A file that cannot be read or parsed yields a notice, not an exception.

Raises:

Type Description
ValueError

If a target does not exist, cannot be fetched, or selects a name that is not an agent or a graph.

export_html

export_html(
    source: Session
    | Agent[Any, Any]
    | Graph[Any, Any, Any, Any]
    | Analysis
    | str
    | PathLike[str],
    path: str | PathLike[str],
) -> Path

Write a self-contained HTML file that opens in any browser, with no server.

The file holds the viewer and the events, so it can be attached to an issue or sent to a colleague. It contains every captured prompt and tool result; treat it like the data it shows.

import pydantic_ai_viz as pviz

pviz.export_html("run.pviz.jsonl", "run.html")  # a recording
pviz.export_html(agent, "blueprint.html")  # structure only, nothing is run
pviz.export_html(pviz.analyze("agents.py"), "blueprint.html")  # read from source, not imported

Parameters:

Name Type Description Default
source Session | Agent[Any, Any] | Graph[Any, Any, Any, Any] | Analysis | str | PathLike[str]

What to export. A Session gives everything it has captured so far; a path gives that .pviz.jsonl recording; an Agent, a Graph or an Analysis gives blueprints only, with no runs.

required
path str | PathLike[str]

Where to write the HTML file. An existing file is replaced.

required

Returns:

Type Description
Path

The path written.

Raises:

Type Description
OSError

If a recording cannot be read or the file cannot be written.

ValueError

If source is a path to something that is not a recording.

TypeError

If source is none of the accepted kinds.

run_graph async

run_graph(
    graph: Graph[Any, Any, Any, Any],
    *,
    state: Any = None,
    deps: Any = None,
    inputs: Any = None,
    session: Session | None = None,
) -> Any

Run a pydantic-graph Graph so the viewer can follow it node by node.

A drop-in for await graph.run(state=..., deps=..., inputs=...). The graph is registered with the session if it is not yet. Agent runs started inside a step appear under that step's node.

import pydantic_ai_viz as pviz

with pviz.record(graph) as session:
    output = await pviz.run_graph(graph, inputs="hello")

Known limits, while several nodes run in parallel (after a broadcast or a map): an agent run started by one of the nodes of a batch is shown under the graph run, not under its node; and a failure is shown on the graph run only, because the graph does not say which of the running nodes raised.

Parameters:

Name Type Description Default
graph Graph[Any, Any, Any, Any]

The graph to run.

required
state Any

Passed to the graph as its state.

None
deps Any

Passed to the graph as its dependencies.

None
inputs Any

Passed to the graph as the input of its first node.

None
session Session | None

The session to report to. Defaults to the open session; when there is none, the graph simply runs untraced.

None

Returns:

Type Description
Any

The graph's output.

blueprint

blueprint(
    target: AnyAgent | AnyGraph,
) -> AgentBlueprint | GraphBlueprint

Describe an agent or a graph without running it.

Pure: no model call, no server, no session, nothing global is touched. The result is a pydantic model; .model_dump(mode="json") gives the wire form.

The blueprint's id is "a1" (agent) or "g1" (graph). Sub-agents found by reading the tools' code are referenced from delegates as "a2", "a3", ... in discovery order; a tool that calls its own agent points at "a1".

Parameters:

Name Type Description Default
target AnyAgent | AnyGraph

A pydantic_ai.Agent or a pydantic_graph.Graph.

required

Returns:

Type Description
AgentBlueprint | GraphBlueprint

An AgentBlueprint or a GraphBlueprint. Anything that could not be

AgentBlueprint | GraphBlueprint

read from the installed pydantic-ai version is listed in warnings.

Raises:

Type Description
TypeError

If target is neither an agent nor a graph.

serve

serve(
    *targets: Target,
    host: str = DEFAULT_HOST,
    port: int = DEFAULT_PORT,
    open_browser: bool = False,
    include_content: bool = True,
    stream: bool = False,
    instrument: bool = True,
    title: str | None = None,
    max_events: int = DEFAULT_MAX_EVENTS,
) -> Session

Capture agent runs in this process and show them live in a local viewer.

Starts a small HTTP server in a background thread and returns at once. Every agent run that happens while the session is open appears in the viewer as it happens, whether or not the agent was passed here; passing it adds its full static blueprint before the first run.

import pydantic_ai_viz as pviz

with pviz.serve(agent, open_browser=True) as session:
    print(session.url)
    agent.run_sync("Hello")
    session.wait()  # keep serving until Ctrl+C

Parameters:

Name Type Description Default
*targets Target

Agents, graphs, modules whose module-level agents and graphs are all registered, or the result of analyze().

()
host str

Address to bind. The default is reachable from this machine only. Any other address serves prompts and tool results to the network with no authentication, and a warning says so.

DEFAULT_HOST
port int

Port to bind. If it is busy a free port is used instead; 0 always picks a free port. The address really used is session.url.

DEFAULT_PORT
open_browser bool

Open the viewer in the default browser.

False
include_content bool

Capture prompts, tool arguments and results. With False the structure of each run is kept and the content is null.

True
stream bool

Capture token deltas. This switches model requests of the registered agents to streaming, so a model that cannot stream will fail. Has no effect with include_content=False: token deltas are content.

False
instrument bool

Call Agent.instrument_all with this session's own tracer provider. With False nothing global is touched; add session.span_processor to your own provider instead.

True
title str | None

Session title, shown in the viewer and used for download file names. Defaults to the name of the first named target.

None
max_events int

Size of the event log before whole completed runs are dropped.

DEFAULT_MAX_EVENTS

Returns:

Type Description
Session

The open session. Its url is the viewer's address.

Raises:

Type Description
RuntimeError

If instrument is true and another instrumenting session is open.

TypeError

If a target is not an agent, a graph, a module or an Analysis.

OSError

If the server cannot bind host at all.

record

record(
    *targets: Target,
    include_content: bool = True,
    stream: bool = False,
    instrument: bool = True,
    title: str | None = None,
    max_events: int = DEFAULT_MAX_EVENTS,
) -> Session

Capture agent runs in this process, without starting a server.

Every agent run that happens while the session is open is recorded, whether or not the agent was passed here; passing it adds its full static blueprint.

import pydantic_ai_viz as pviz

with pviz.record(agent) as session:
    agent.run_sync("Hello")
print(len(session.events))

Parameters:

Name Type Description Default
*targets Target

Agents, graphs, modules whose module-level agents and graphs are all registered, or the result of analyze().

()
include_content bool

Capture prompts, tool arguments and results. With False the structure of each run is kept and the content is null.

True
stream bool

Capture token deltas. This switches model requests of the registered agents to streaming, so a model that cannot stream will fail. Has no effect with include_content=False: token deltas are content.

False
instrument bool

Call Agent.instrument_all with this session's own tracer provider. With False nothing global is touched; add session.span_processor to your own provider instead.

True
title str | None

Session title. Defaults to the name of the first named target.

None
max_events int

Size of the event log before whole completed runs are dropped.

DEFAULT_MAX_EVENTS

Returns:

Type Description
Session

The open session.

Raises:

Type Description
RuntimeError

If instrument is true and another instrumenting session is open.

TypeError

If a target is not an agent, a graph, a module or an Analysis.