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, hand-off workflows and pydantic-graph flows. Your code is parsed, never run.

uvx agentsdiagram scan . -f html -o agents.html
Open full screen
examples/support_desk/agents.py excerpt
billing = Agent(
    "openai:gpt-5-mini",
    name="billing",
    toolsets=[crm.prefixed("crm")],
)

tech = Agent(
    "anthropic:claude-sonnet-5-5",
    name="tech",
    tools=[Tool(status_page, takes_ctx=False)],
    toolsets=[help_center],  # MCPToolset
    capabilities=[
        NativeTool(WebSearchTool()),
        Thinking(effort="medium"),
    ],
)

triage = Agent("openai:gpt-5", name="triage")

@triage.tool
async def ask_billing(ctx, question: str) -> str:
    # an agent run inside a tool: delegation
    r = await billing.run(question, deps=ctx.deps)
    return r.output

The diagram also reads tools.py, escalation.py and flow.py. Full source

This is the real viewer, generated by agentsdiagram scan from the examples folder. Click a node to see where it is defined; drag, zoom and filter by kind.

How it works

agentsdiagram is static analysis. It parses your Python files with LibCST and looks for the constructs each framework uses to declare agents, tools and their wiring. Nothing is imported or executed: no API keys, no dependencies of your project, no network.

The result is a small, versioned JSON graph. The CLI turns it into Mermaid, Markdown or a self-contained HTML page; the VS Code extension keeps it next to your code and redraws it as you type.

Anything that only exists at runtime, like tools fetched from a server or lists built in a loop, shows up as a dashed dynamic node instead of silently disappearing.

  1. your code.py files, read as text
  2. adapterspydantic_ai, smolagents
  3. IRversioned JSON graph
  4. Mermaid · HTML viewer · VS Codefront ends

The code stays the source of truth. The diagram is drawn from it on every scan and on every keystroke in VS Code; there is no second model to keep in sync.

What it understands

PydanticAI 2.xsmolagents 1.x
Agents Agent(...), Agent.from_file("spec.yaml"), factories (make_agent()) CodeAgent, ToolCallingAgent
Tools @agent.tool, @agent.tool_plain, tools=[f, Tool(...)] @tool, Tool subclasses, default tools, add_base_tools
Toolsets FunctionToolset, wrappers (.prefixed(), .filtered()…), @agent.toolset ToolCollection, Hub/Space/LangChain sources
MCP MCPToolset(...), load_mcp_toolsets("mcp.json"), MCP(url=...) ToolCollection.from_mcp, MCPClient
Multi-agent agent run inside a tool, SubAgents, hand-off functions managed_agents=[...]
Flows pydantic-graph GraphBuilder (steps, decisions, joins) and BaseNode —
Checks v1 API still in use managed agents without name/description, @tool without hints, name clashes

Full coverage matrices: PydanticAI · smolagents

Get it

  1. Run it once, nothing to install

    With uv, from the root of your project:

    uvx agentsdiagram scan .

    Prints Mermaid. Add -f html -o agents.html for the interactive page, -f markdown for GitHub, or run agentsdiagram check . in CI.

  2. Keep it next to your code

    The Agents Diagram extension shows a live diagram that follows your edits, with “Show in diagram” code lenses and diagnostics. It runs the CLI through uv.

    Open VSX covers Cursor, Windsurf and Positron.

  3. Or install the CLI

    uv tool install agentsdiagram

    Also on PyPI (pip install agentsdiagram). Python 3.11+.

Roadmap

v0.3 Plan
Draw agents and tools that do not exist yet; agentsdiagram writes the stubs.
v0.4 Edit
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.
later More frameworks
Through adapters. See adding a framework.