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

🚀 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))

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

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