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
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
@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],
)
# written by agentsdiagram edit / the diagram
@tool
def search_flights(origin: str, destination: str,
date: str) -> list[dict]:
"""Flights between two cities on a date.
Args: ...
"""
raise NotImplementedError("agentsdiagram: planned")
maps_mcp = MCPClient({"url": "https://maps.example.com/mcp", ...})
# agentsdiagram: planned
booker = ToolCallingAgent(
tools=[search_flights, *maps_mcp.get_tools()],
model=model,
name="booker",
description="Finds and books flights and hotels.",
)
assistant = CodeAgent(
tools=[get_weather, WebSearchTool()],
model=model,
managed_agents=[booker], # added
)
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
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.
- your code.py files, read as text
- adapterssmolagents, pydantic_ai
- IRversioned JSON graph
- 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.x | PydanticAI 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.
- 1One smolagents agentDraw it, read it, let check catch a mistake.
- 2One PydanticAI agentThe same agent, the PydanticAI way: decorators, deps, context.
- 3Teams of agentsManagers, managed agents, delegation, workflows and flows.
- 4Plan before you codeSketch a team in the diagram; get planned stubs in your files.
- 5Edit from the diagramConnect, change models, remove, move to an Agent Spec.
- 6Diagrams in CI and docsGate pull requests and keep a diagram in your README.
- 7With coding agentsGive Claude Code or Codex a map and structural commands.
- →All the docsCommand line, plan and edit, VS Code, coverage, IR.
Get it
-
Run it once, nothing to install
With uv, from the root of your project:
uvx agentsdiagram scan .Prints Mermaid. Add
-f html -o agents.htmlfor the interactive page,-f markdownfor GitHub, runagentsdiagram servefor a live, editable diagram, oragentsdiagram check .in CI. -
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.
-
Or install the CLI
uv tool install agentsdiagramAlso 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.