AgentCanvas – Vstorm's Open Pydantic AI Visualization Tool

1. What Is AgentCanvas

AgentCanvas is an open Pydantic AI visualization tool from Vstorm. It turns Logfire-traced AI Agent run logs into an interactive HTML flowchart showing every model call, tool execution, nested sub-agent, token usage, and exact cost. Output is a single self-contained HTML file viewable offline—ideal for showing clients “what the AI actually did.”

Technical positioning and domain: AI observability and LLM app visualization for the Pydantic AI ecosystem. Parses OpenTelemetry GenAI spans into interactive flowcharts. “Zero-intrusion” and demo-oriented—not a full debugger but offline HTML reports.

Research background: Vstorm works on Agent dev and observability. Pain point: nested Pydantic AI agents are opaque in plain logs; platforms like LangSmith are heavy and cloud-dependent. Built on Logfire’s open tracing as a minimal CLI—“small and focused” open source.

Core value: Fixes two pains: hard-to-debug tool chains; hard-to-explain runs to non-technical clients. Flowcharts give engineers a microscope and sales a projector—less comms cost and debug time.

Technical characteristics: Native recursive rendering for nested sub-agents; precise cost from real token data; no Agent code changes—reads Logfire traces only. Single HTML works offline, email, and client demos.

2. Key Features

• Block flowchart: Full run as User → Agent → Model → Tools → Answer with pan, zoom, drag—see tools called, returns, and final answer at a glance.

• Nested sub-agent recursion: When a tool is another Agent, nested frames recurse to any depth—clarifies “agent calls agent” without Russian-doll black boxes.

• Full conversation log: Each turn in its own frame; sidebar shows full user → assistant → user → assistant transcript for multi-turn debugging.

• Reasoning visualization: Thinking summaries and reasoning token counts on model nodes and transcripts—for o1, DeepSeek-R1, etc.

• Precise cost calculation: genai-prices computes USD per call and total—not just token counts—useful for production cost control and client quotes.

• Token usage stats: Input / Output / Reasoning tokens per layer plus totals—spot expensive steps for prompt or model optimization.

• Deep detail panel: Provider, finish reason, response ID, tool list/descriptions, output schema, thinking config—black-box metadata for deep debug.

• Guided demo mode: Auto-play or step-through (Space/click/arrows, rewind) with narration for client demos.

• Single-file output: One HTML—no build, no server, offline, email-friendly.

3. How to Use

1. Install: pip install agentcanvas (Python 3.10+; use a venv).

2. Read token: Set LOGFIRE_READ_TOKEN (or .env) from Logfire Project Settings with read access for Query API.

3. (Optional) Region URL: For EU Logfire, set LOGFIRE_BASE_URL= (link to be updated upon official release) per project region.

4. Latest run report: agentcanvas reads latest trace, writes agent_flow.html, opens browser.

5. List runs: agentcanvas --list shows recent traces with ID, time, summary.

6. Specific trace: agentcanvas --trace-id <id> for a chosen run—compare versions or replay incidents.

7. Custom output: agentcanvas -o report.html --no-open for batch/CI paths.

8. (Optional) Example agent: In repo: uv sync --all-extras --prerelease=allow then uv run --prerelease=allow python assets/scripts/main.py for sample trace, then agentcanvas.

9. Library mode: Import LogfireClient, parse_run, render_html in Python for CI/CD or test artifacts.

4. Pros and Cons

5. Comparison with Similar Tools

Selection guidance: Pydantic AI projects needing client reports and cost audit: AgentCanvas—zero intrusion, single file, MIT. LangChain teams needing online debug, prompts, A/B: LangSmith. Privacy/self-host: Phoenix Apache 2.0—but less intuitive viz and no demo mode vs AgentCanvas.

6. Editor's Take

AgentCanvas nails a niche—Pydantic AI “visualize + present.” Recursive sub-agent rendering and real-dollar costs are rare depth. Turning reports into narrated demos reframes the problem: help non-technical stakeholders understand AI, not just engineers.

It solves debug black boxes and delivery communication—explaining three API calls, cost, and decisions often matters more than the code. Single HTML makes sharing free.

Best for: Pydantic AI builders with nested agents; client/demo presenters; cost-focused ops/finance. Less value on LangChain/CrewAI—tightly coupled to Pydantic AI + Logfire.

Future: more trace backends, run-vs-run diff, internal platform APIs. MIT + Vstorm’s Pydantic depth are solid foundations.

Best visualization report tool in Pydantic AI today—precise, easy, open. −0.5 for Logfire lock-in and young community/docs.

7. Use Cases

• Client demos and reviews: Show full decision chain, tool order, live cost in meetings—guided mode for non-technical audiences.

• Production debugging: Find wrong tool calls or token spikes visually vs log grep.

• Cost audit and optimization: Per-call USD to tune prompts/models when one tool burns output tokens.

• Architecture documentation: Runtime flowcharts as deliverables vs static diagrams.

• Multi-agent monitoring: Recursive view through agent → sub-agent → sub-sub-agent stacks.

8. FAQ

Q: Non-Pydantic AI frameworks?
A: No. Requires Logfire GenAI span format tied to Pydantic AI. LangChain/CrewAI on Logfire still won’t parse correctly—use Phoenix or LangSmith.

Q: Which browsers?
A: Modern Chrome, Firefox, Safari, Edge—HTML5/CSS3/JS self-contained, offline. No IE.

Q: Cost accuracy?
A: genai-prices with official pricing for GPT-4, Claude 3, Gemini, etc., using logged Input/Output/Reasoning tokens. Custom/private models need manual price updates.

Q: Long runs / huge token bills?
A: Supported; HTML size grows with complexity—hundreds of tool calls may yield tens of MB and slight browser lag. Test before big demos.

Q: CI integration?
A: Yes—library mode with LogfireClient, parse_run, render_html for automated HTML artifacts after tests.

Q: If Logfire project deleted or token expired?
A: Generated HTML still works—all data embedded. True offline archive advantage.

9. Project Links

• GitHub: https://github.com/vstorm-co/agentcanvas