agentcanvas

KO | EN

gitlite — search

#python #llm #go #machine-learning #deep-learning #awesome #cli #kubernetes #awesome-list #vue #pytorch #security #openai #mcp

(★ 79)

Visualize Pydantic AI agent workflows from Logfire traces as an interactive HTML diagram — tools, nested sub-agents, tokens and exact cost.

agentcanvas 최신버젼 다운로드

최종 버전 다운로드 (.zip)

// repository documentation

Was this content helpful?

★ 0 (0 ratings)

<h1 align="center">agentcanvas</h1>

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.

<a href="#-what-it-shows">Features</a> &middot;
 <a href="#-quick-start">Quick start</a> &middot;
 <a href="#-how-it-works">How it works</a> &middot;
 <a href="#-architecture">Architecture</a> &middot;
 <a href="CONTRIBUTING.md">Contributing</a>

<table>
<tr>
<td width="50%"><img src="assets/screenshot-inspector.png" alt="Model call inspector"> Click any node for a full inspector — tokens, exact cost, reasoning, the tools the model could call.</td>
<td width="50%"><img src="assets/screenshot-conversation.png" alt="Conversation transcript"> The full multi-turn conversation, with tool calls and reasoning.</td>
</tr>
<tr>
<td width="50%"><img src="assets/screenshot-tool.png" alt="Tool inspector"> Per-tool input, output and timing.</td>
<td width="50%"><img src="assets/screenshot-tour.png" alt="Guided tour"> A guided tour (auto or manual) narrates each step for client demos.</td>
</tr>
</table>

---

## 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

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

---

## 🚀 Quick start

```bash
pip install agentcanvas
```

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

```bash
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:

```python
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:

```bash
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

```bash
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](CONTRIBUTING.md) for details.

---

## Changelog

See [CHANGELOG.md](CHANGELOG.md).

## License

MIT — see [LICENSE](LICENSE).

---

### Need help shipping AI agents in production?

We're <a href="https://vstorm.co">Vstorm</a> — an Applied Agentic AI Engineering Consultancy 
with 30+ production agent implementations.

Made with **care** by <a href="https://vstorm.co">Vstorm.co</a>

</div>

agentcanvas

agentcanvas 최신버젼 다운로드

오늘의 추천 프로젝트

Was this content helpful?

Recent Feedback

agentcanvas

agentcanvas 최신버젼 다운로드

오늘의 추천 프로젝트

Was this content helpful?

Recent Feedback

Download README