agentsdiagram

See your AI agents. agentsdiagram reads the code of your PydanticAI and smolagents agents and draws them: agents, tools, toolsets, MCP servers, capabilities, delegation between agents, hand-off workflows and pydantic-graph flows.

It is static analysis: your code is parsed, never imported or executed. No API keys, no dependencies of your project, no network.

• CLI: Mermaid, JSON or a self-contained interactive HTML page.
• VS Code extension (also on Open VSX for Cursor, Windsurf and Positron): a live diagram next to your code that follows your edits, "Show in diagram" code lenses and diagnostics.

Quick start

uvx agentsdiagram scan path/to/project                    # Mermaid to stdout
uvx agentsdiagram scan . -f html -o agents.html           # interactive page, open it in any browser
uvx agentsdiagram scan . -f markdown -o AGENTS-DIAGRAM.md # renders on GitHub
uvx agentsdiagram check .                                 # diagnostics; exit 1 on errors (CI, pre-commit)

Or install it: uv tool install agentsdiagram / pip install agentsdiagram.

agentsdiagram scan [PATH] [-f mermaid|json|html|markdown] [-o FILE] [--framework pydantic_ai|smolagents]
                   [--include GLOB] [--exclude GLOB] [--title TEXT]
agentsdiagram check [PATH] [--strict] [--json]
agentsdiagram schema        # JSON Schema of the IR
agentsdiagram lsp           # language server (needs agentsdiagram[lsp]); used by the extension

Project-wide settings go in pyproject.toml:

[tool.agentsdiagram]
include = ["src/**"]
exclude = ["tests/**", "notebooks/**"]

What it understands

Anything that only exists at runtime (lists built in a loop, tools fetched from a server) shows up as a dashed dynamic node instead of silently disappearing. Full coverage matrices: PydanticAI · smolagents.

VS Code extension

Install Agents Diagram from the Marketplace or Open VSX. It needs either uv (the extension runs uvx agentsdiagram[lsp]) or your own command in agentsdiagram.server.command. The Python extension is not required. See packages/vscode/README.md.

How it works

your code ──LibCST──▶ adapters (pydantic_ai, smolagents) ──▶ facts ──link──▶ IR (JSON)
                                                                         ├─▶ Mermaid
                                                                         ├─▶ HTML viewer (React Flow)
                                                                         └─▶ LSP ─▶ VS Code panel

The IR is a small, versioned JSON format (docs/ir.md); the viewer and the extension use TypeScript types generated from its JSON Schema. Architecture and design decisions: docs/architecture.md.

Roadmap

• Plan (v0.3): draw agents and tools that do not exist yet; agentsdiagram writes the stubs.
• Edit (v0.4): connect, add and remove tools and agents in the diagram; the change is written to your code with LibCST, preserving formatting. The code stays the single source of truth.
• More frameworks through adapters (docs/adding-a-framework.md).

Development

uv sync                      # Python 3.11+, includes pydantic-ai and smolagents for the oracle tests
pnpm install && pnpm build   # viewer + extension (pnpm 11, Node 22+)
uv run pytest                # unit, snapshot, oracle, drift and LSP tests
pnpm test                    # viewer (vitest) + extension smoke test

More in docs/architecture.md and docs/releasing.md.

License

MIT © 2026 Alex Ojeda Copa