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
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],
)
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.
- your code.py files, read as text
- adapterspydantic_ai, smolagents
- IRversioned JSON graph
- 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.x | smolagents 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
-
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, or runagentsdiagram check .in CI. -
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.
-
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.
- 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.