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
🚀 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?
Made with care by Vstorm.co