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, delegation, workflows and flows. Then it works the other way round: plan agents and tools in the diagram and they are written to your code. Static analysis: your code is parsed, never run.

uvx agentsdiagram serve
Open full screen
examples/research_team/team.py excerpt
@tool
def plot(path: str, x: str, y: str) -> str:
    """Draw a line chart and return the image path."""

web_researcher = ToolCallingAgent(
    tools=[WebSearchTool(), VisitWebpageTool()],
    model=model,
    name="web_researcher",
    description="Searches the web, reads pages.",
)

analyst = CodeAgent(
    tools=[CsvSummary(), plot],
    model=model,
    name="analyst",
    description="Analyses CSV data.",
)

papers = StdioServerParameters(command="uvx", ...)

with ToolCollection.from_mcp(papers, ...) as arxiv:
    lead = CodeAgent(
        tools=[*arxiv.tools],
        model=model,
        managed_agents=[web_researcher, analyst],
    )

One file: a manager CodeAgent with two managed agents and MCP tools. Full source

This is the real viewer, generated by agentsdiagram scan from the examples folder; the planned tab was written by the planner itself. Click a node to see where it is defined; drag, zoom and filter by kind. Editing is on in VS Code and agentsdiagram serve.

Plan and edit, in the diagram

Plan. Sketch a system before you write it. Plan agent and Add tool write planned stubs to your files: typed, documented, importable, and drawn dashed until you implement them. agentsdiagram check lists what is left.

Edit. Hand work from one agent to another, add an MCP server, change a model or the instructions, disconnect or remove. In smolagents that means managed_agents, @tool stubs and MCPClient; in PydanticAI, delegation tools, MCPToolset and Agent Specs.

Safe. Changes are made with LibCST: the rest of the file keeps its formatting, imports land where they belong, and in VS Code everything can be undone. Edits are refused if the code changed since the diagram was drawn.

agentsdiagram edit connect lead analyst

What each operation writes · Tutorial: plan before you code

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; serve and the VS Code extension keep it live and redraw it as you type. Edits made on the graph go back through the same pipeline as minimal changes to your files.

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. adapterssmolagents, pydantic_ai
  3. IRversioned JSON graph
  4. Mermaid · HTML · serve · VS Codefront ends, and edits back to your code

The code stays the source of truth. The diagram is drawn from it on every scan and every keystroke, and edits are written to it; there is no project file and no second model to keep in sync.

What it understands

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

Full coverage: smolagents · PydanticAI

Learn it in an afternoon

Seven short tutorials, from one agent to a planned team, with live diagrams in every page.

  1. 1One smolagents agentDraw it, read it, let check catch a mistake.
  2. 2One PydanticAI agentThe same agent, the PydanticAI way: decorators, deps, context.
  3. 3Teams of agentsManagers, managed agents, delegation, workflows and flows.
  4. 4Plan before you codeSketch a team in the diagram; get planned stubs in your files.
  5. 5Edit from the diagramConnect, change models, remove, move to an Agent Spec.
  6. 6Diagrams in CI and docsGate pull requests and keep a diagram in your README.
  7. 7With coding agentsGive Claude Code or Codex a map and structural commands.
  8. →All the docsCommand line, plan and edit, VS Code, coverage, IR.

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, run agentsdiagram serve for a live, editable diagram, or agentsdiagram check . in CI.

  2. Keep it next to your code

    The Agents Diagram extension shows a live diagram that follows your edits, lets you plan and edit from it (with undo), and adds “Show in diagram” code lenses and diagnostics. It runs the analyzer 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. Shipped.
v0.4 Edit
Connect, add and remove tools and agents, change models, from the diagram or the CLI. Shipped.
next More frameworks
OpenAI Agents, Google ADK, Agno, Strands, LangGraph, through adapters. See adding a framework.
later Your layout
Keep a hand-arranged layout next to the code, matched by kind, file and name.