agentsdiagram

See, plan and edit your AI agents. agentsdiagram reads the code of your smolagents and PydanticAI agents and draws them: agents, tools, MCP servers, managed agents and delegation, hand-off workflows and pydantic-graph flows. Then it lets you change them from the diagram: plan agents and tools that do not exist yet, connect agents, swap models. Every change is written to your code.

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

Website, tutorials and live demos: https://alex-roc.github.io/agentsdiagram/

Quick start

uvx agentsdiagram scan . -f html -o agents.html   # an interactive page, open it in any browser
uvx agentsdiagram serve                           # the same, live and editable, at http://127.0.0.1:8765
uvx agentsdiagram check .                         # diagnostics; exit 1 on errors (CI, pre-commit)

Or install it: uv tool install agentsdiagram / pip install agentsdiagram (Python 3.11+). In your editor: the Agents Diagram extension for VS Code and Open VSX (Cursor, Windsurf, Positron).

See

from smolagents import CodeAgent, InferenceClientModel, WebSearchTool, tool


@tool
def get_weather(city: str) -> str:
    """Current weather for a city.

    Args:
        city: Name of the city.
    """
    return "sunny"


assistant = CodeAgent(tools=[get_weather, WebSearchTool()], model=InferenceClientModel())

agentsdiagram scan turns that into a diagram with the agent, its model and its two tools, and it scales to teams: managers and managed agents, agents that delegate to agents inside tools, MCP servers, toolsets and their wrappers, workflows that run agents in order, pydantic-graph flows. Click a node for its details and "Go to code"; / searches; the legend filters. Anything that only exists at runtime shows up as a dashed dynamic node instead of silently disappearing.

agentsdiagram check catches mistakes the libraries only report at runtime, if at all: a smolagents managed agent without a description, a @tool without type hints, two tools with the same name, PydanticAI v1 API.

Plan

Sketch a system before writing it. Plan agent in the diagram, or agentsdiagram edit add-agent, writes a planned agent; Add tool writes a typed stub that raises NotImplementedError("agentsdiagram: planned"). The plan is real, importable code, drawn with a dashed outline until you implement it, and agentsdiagram check lists what is left to do.

agentsdiagram edit add-agent booker --parent assistant --description "Finds and books flights."
agentsdiagram edit add-tool booker search_flights --params "origin: str, destination: str, date: str"
agentsdiagram edit add-mcp booker --url https://maps.example.com/mcp

Edit

Connect agents (managed_agents in smolagents, a delegation tool in PydanticAI), add MCP servers, change models and instructions, disconnect and remove, or move a PydanticAI agent's settings to an Agent Spec. Changes are made with LibCST, so the rest of the file keeps its formatting, imports are added where they belong, and in VS Code every change can be undone. The code stays the only source of truth: there is no project file and nothing to sync. How it works.

What it understands

Full coverage: smolagents · PydanticAI.

Learn

• Getting started
• Tutorials: 1. One smolagents agent · 2. One PydanticAI agent · 3. Teams of agents · 4. Plan before you code · 5. Edit from the diagram · 6. Diagrams in CI and docs · 7. With coding agents
• Guides: command line · plan and edit · VS Code extension
• Examples, from one agent to a team: examples/

How it works

your code ──LibCST──▶ adapters (smolagents, pydantic_ai) ──▶ IR (JSON) ─┬─▶ Mermaid / Markdown
    ▲                                                                   ├─▶ HTML viewer (React Flow)
    │                                                                   ├─▶ serve (live, editable)
    └──────────── edits (LibCST, minimal diffs) ◀── edit protocol ◀─────┴─▶ 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

• More frameworks through adapters (docs/adding-a-framework.md): OpenAI Agents, Google ADK, Agno, Strands, LangGraph.
• Keep a hand-arranged layout (.agentsdiagram/layout.json, matched by kind, file and name).
• Import and export smolagents agent.json.

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, edit, serve 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