Agent visualization

Agent visualization allows you to generate a structured graphical representation of agents and their relationships using Graphviz. This is useful for understanding how agents, tools, and handoffs interact within an application.

Installation

Install the optional viz dependency group:

pip install "openai-agents[viz]"

Generating a graph

You can generate an agent visualization using the draw_graph function. This function creates a directed graph where:

• Agents are represented as yellow boxes.
• MCP servers are represented as grey boxes.
• Tools are represented as green ellipses.
• Handoffs are directed edges from one agent to another.

Example usage

import os

from agents import Agent, function_tool
from agents.mcp.server import MCPServerStdio
from agents.extensions.visualization import draw_graph

@function_tool
def get_weather(city: str) -> str:
    return f"The weather in {city} is sunny."

spanish_agent = Agent(
    name="Spanish agent",
    instructions="You only speak Spanish.",
)

english_agent = Agent(
    name="English agent",
    instructions="You only speak English",
)

current_dir = os.path.dirname(os.path.abspath(__file__))
samples_dir = os.path.join(current_dir, "sample_files")
mcp_server = MCPServerStdio(
    name="Filesystem Server, via npx",
    params={
        "command": "npx",
        "args": ["-y", "@modelcontextprotocol/server-filesystem", samples_dir],
    },
)

triage_agent = Agent(
    name="Triage agent",
    instructions="Handoff to the appropriate agent based on the language of the request.",
    handoffs=[spanish_agent, english_agent],
    tools=[get_weather],
    mcp_servers=[mcp_server],
)

draw_graph(triage_agent)

This generates a graph that visually represents the structure of the triage agent and its connections to sub-agents and tools.

Understanding the visualization

The generated graph includes:

• A start node (__start__) indicating the entry point.
• Agents represented as rectangles with yellow fill.
• Tools represented as ellipses with green fill.
• MCP servers represented as rectangles with grey fill.
• Directed edges indicating interactions:
  • Solid arrows for agent-to-agent handoffs.
  • Dotted arrows for tool invocations.
  • Dashed arrows for MCP server invocations.
• An end node (__end__) indicating where execution terminates.

Note: MCP servers are rendered in recent versions of the agents package (verified in v0.2.8). If you don’t see MCP boxes in your visualization, upgrade to the latest release.

Customizing the graph

Showing the graph

By default, draw_graph displays the graph inline. To show the graph in a separate window, write the following:

draw_graph(triage_agent).view()

Saving the graph

By default, draw_graph displays the graph inline. To save it as a file, specify a filename:

draw_graph(triage_agent, filename="agent_graph")

This will generate agent_graph.png in the working directory.