Python API¶
Everything public is importable from the top-level package. The examples in these docs use the alias 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.
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.TypeErrorif a target is not an agent, a graph, a module or anAnalysis.OSErrorif the server cannot bindhostat 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¶
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.
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.
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:
servecaptures runs and shows them live in a local viewer.recordcaptures runs without a server.analyzereads agents and graphs out of source files, without importing them.blueprintdescribes a live agent or graph as data, without running it.export_htmlwrites a single-file HTML export.run_graphruns a pydantic-graphGraphso its nodes are captured.Sessionis whatserveandrecordreturn.AgentBlueprintandGraphBlueprintare the modelsblueprintreturns.Analysisis whatanalyzereturns;Limitsbounds 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 |
graphs |
list[GraphBlueprint]
|
One blueprint per |
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 |
title |
str | None
|
A short name for what was analysed: the file, directory or module,
or |
blueprints
property
¶
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
¶
A larger file is skipped, with a notice.
max_files
class-attribute
instance-attribute
¶
No more files than this are read in one analysis.
max_seconds
class-attribute
instance-attribute
¶
Reading stops, with a notice, once this much time has passed. Fetching is timed separately.
max_fetch_seconds
class-attribute
instance-attribute
¶
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 |
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
|
|
include_content |
Whether prompts, tool arguments and results are captured. |
|
stream |
Whether token deltas are captured. Always |
Open a session. Prefer record() or serve(), which also register targets.
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
title
|
str | None
|
Session title; defaults to |
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 |
False
|
instrument
|
bool
|
Call |
True
|
max_events
|
int
|
Size of the event log before whole completed runs are dropped. |
DEFAULT_MAX_EVENTS
|
mode
|
SessionMode
|
|
'capture'
|
notices
|
Sequence[str]
|
Messages about the session as a whole, shown by the viewer. |
()
|
Raises:
| Type | Description |
|---|---|
RuntimeError
|
If |
ValueError
|
If |
events
property
¶
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
¶
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]).
register
¶
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 |
save
¶
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
¶
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
¶
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
¶
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
¶
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:nameselects the agent or graph assigned tonameat the top level of that file. - A directory. Every
.pyfile below it is read. Virtual environments,node_modules,site-packages,__pycache__,build,distand hidden directories are passed over; abuildordistthat holds.pyfiles is named in a notice. - A module name,
package.moduleorpackage.module:name. The file is found on disk, below the working directory, itssrcdirectory or an entry ofsys.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 shortgh:owner/repo[@ref][/subdir]. A ref is a branch, a tag or a full commit SHA. The commit is fetched withgitinto 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 |
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 |
TypeError
|
If |
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
¶
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 |
required |
Returns:
| Type | Description |
|---|---|
AgentBlueprint | GraphBlueprint
|
An |
AgentBlueprint | GraphBlueprint
|
read from the installed pydantic-ai version is listed in |
Raises:
| Type | Description |
|---|---|
TypeError
|
If |
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 |
()
|
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; |
DEFAULT_PORT
|
open_browser
|
bool
|
Open the viewer in the default browser. |
False
|
include_content
|
bool
|
Capture prompts, tool arguments and results. With |
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 |
False
|
instrument
|
bool
|
Call |
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 |
Raises:
| Type | Description |
|---|---|
RuntimeError
|
If |
TypeError
|
If a target is not an agent, a graph, a module or an |
OSError
|
If the server cannot bind |
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 |
()
|
include_content
|
bool
|
Capture prompts, tool arguments and results. With |
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 |
False
|
instrument
|
bool
|
Call |
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 |
TypeError
|
If a target is not an agent, a graph, a module or an |