agentcanvas

See exactly how your AI agent works.
Turn Pydantic AI runs logged to Logfire into a polished, animated diagram of the whole workflow — every model call, tool, nested sub-agent, token and dollar.

Features · Quick start · How it works · Architecture · Contributing

Click any node for a full inspector — tokens, exact cost, reasoning, the tools the model could call.	The full multi-turn conversation, with tool calls and reasoning.
Per-tool input, output and timing.	A guided tour (auto or manual) narrates each step for client demos.

---

Why

Clients rarely understand what an "AI agent" actually does. They see a prompt and an answer — not the reasoning, the tool calls, the sub-agents, or the cost. agentcanvas reads the trace your agent already sends to Logfire and renders it as a clear, interactive block diagram you can put on screen in a meeting: this is the question, here is what the model decided, these are the tools it ran, this is what each step cost, and here is the answer.

---

✨ What it shows

🧩 Block diagram	The full run as a flow: User → Agent → model call → tools → model call → answer, on a pan / zoom / drag canvas.
🪆 Nested agents	When a tool is itself another agent (with its own tools), it is drawn as a nested frame — recursively, to any depth. The diagram grows with the system.
💬 Full conversation	Every turn is its own frame, connected in sequence. A side panel shows the complete user → assistant → user → assistant transcript.
🧠 Reasoning	The model's "thinking" summary and reasoning-token counts, shown on each model call and in the transcript.
💰 Exact cost	Per model call and for the whole run, computed from tokens via genai-prices.
🔢 Token usage	Input / output / reasoning tokens, per step and aggregated.
🔎 Deep detail	Provider, finish reason, response id, the tools available to the model (with descriptions), output mode and thinking config — in a click-through, resizable inspector.
🎬 Guided tour	An auto walkthrough and a manual step mode (Space / click / arrows, with back), each with plain-language narration for client demos.
📦 Self-contained	The output is a single HTML file — no server, no build, works offline, easy to send.

---

🚀 Quick start

pip install agentcanvas

Set LOGFIRE_READ_TOKEN in your environment (or a .env file), then build the report from your latest agent run:

agentcanvas                       # latest run → agent_flow.html (opens in browser)
agentcanvas --list                # list recent runs
agentcanvas --trace-id <id>       # a specific run
agentcanvas -o report.html --no-open

Or use it as a library:

from agentcanvas import LogfireClient, parse_run, render_html

client = LogfireClient()                       # reads LOGFIRE_READ_TOKEN
trace_id = client.latest_trace_id()
report = parse_run(client.fetch_trace(trace_id), trace_id)
open("report.html", "w").write(render_html(report))

Variable	Used for
LOGFIRE_READ_TOKEN	reading traces via the Logfire Query API (required)
LOGFIRE_BASE_URL	optional region override (default US; EU: https://logfire-eu.pydantic.dev)
LOGFIRE_WRITE_TOKEN	the example agent sending telemetry to Logfire
OPENROUTER_API_KEY	the example agent (model via OpenRouter)

Try the example agent

The repo ships a runnable example (assets/scripts/main.py) — a thinking agent with five tools, a nested sub-agent and a multi-turn conversation. From a checkout:

uv sync --all-extras --prerelease=allow              # installs the `demo` extra
uv run --prerelease=allow python assets/scripts/main.py   # generates a sample trace in Logfire
agentcanvas                                       # visualize it

---

🔍 How it works

Logfire (OpenTelemetry GenAI spans)  ──query──►  parser  ──►  payload  ──render──►  agent_flow.html

Pydantic AI's instrumentation emits OpenTelemetry GenAI spans (invoke_agent, chat, execute_tool). agentcanvas reads them through the Logfire Query API (SQL + a read token), rebuilds the span tree into a recursive workflow (turns → rounds → tools → nested agents), prices it with genai-prices, and renders a single self-contained HTML report.

---

🏗️ Architecture

Module	Role
logfire_client.py	Logfire Query API client (SQL → rows)
parser.py	span tree → recursive payload (turns, rounds, tools, nested agents)
pricing.py	exact cost from tokens via genai-prices
render.py	payload → embedded HTML / CSS / JS report
viz.py	CLI entry point
assets/scripts/main.py	demo agent: thinking, five tools, a nested sub-agent, a multi-turn conversation
assets/scripts/make_demo.py · make_screenshots.py	record the demo video / capture doc screenshots

---

Development

git clone https://github.com/vstorm-co/agentcanvas.git
cd agentcanvas
make install      # uv sync (incl. dev tools)
make all          # ruff + mypy + pytest

The library is fully typed and tested; make all must pass before a PR. See CONTRIBUTING.md for details.

---

Changelog

See CHANGELOG.md.

License

MIT — see LICENSE.

---

Need help shipping AI agents in production?

We're Vstorm — an Applied Agentic AI Engineering Consultancy
with 30+ production agent implementations.

Made with care by Vstorm.co