|
| 1 | +# Agent Visualization |
| 2 | + |
| 3 | +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. |
| 4 | + |
| 5 | +## Installation |
| 6 | + |
| 7 | +Install the optional `viz` dependency group: |
| 8 | + |
| 9 | +```bash |
| 10 | +pip install "openai-agents[viz]" |
| 11 | +``` |
| 12 | + |
| 13 | +## Generating a Graph |
| 14 | + |
| 15 | +You can generate an agent visualization using the `draw_graph` function. This function creates a directed graph where: |
| 16 | + |
| 17 | +- **Agents** are represented as yellow boxes. |
| 18 | +- **Tools** are represented as green ellipses. |
| 19 | +- **Handoffs** are directed edges from one agent to another. |
| 20 | + |
| 21 | +### Example Usage |
| 22 | + |
| 23 | +```python |
| 24 | +from agents import Agent, function_tool |
| 25 | +from agents.extensions.visualization import draw_graph |
| 26 | + |
| 27 | +@function_tool |
| 28 | +def get_weather(city: str) -> str: |
| 29 | + return f"The weather in {city} is sunny." |
| 30 | + |
| 31 | +spanish_agent = Agent( |
| 32 | + name="Spanish agent", |
| 33 | + instructions="You only speak Spanish.", |
| 34 | +) |
| 35 | + |
| 36 | +english_agent = Agent( |
| 37 | + name="English agent", |
| 38 | + instructions="You only speak English", |
| 39 | +) |
| 40 | + |
| 41 | +triage_agent = Agent( |
| 42 | + name="Triage agent", |
| 43 | + instructions="Handoff to the appropriate agent based on the language of the request.", |
| 44 | + handoffs=[spanish_agent, english_agent], |
| 45 | + tools=[get_weather], |
| 46 | +) |
| 47 | + |
| 48 | +draw_graph(triage_agent) |
| 49 | +``` |
| 50 | + |
| 51 | + |
| 52 | + |
| 53 | +This generates a graph that visually represents the structure of the **triage agent** and its connections to sub-agents and tools. |
| 54 | + |
| 55 | + |
| 56 | +## Understanding the Visualization |
| 57 | + |
| 58 | +The generated graph includes: |
| 59 | + |
| 60 | +- A **start node** (`__start__`) indicating the entry point. |
| 61 | +- Agents represented as **rectangles** with yellow fill. |
| 62 | +- Tools represented as **ellipses** with green fill. |
| 63 | +- Directed edges indicating interactions: |
| 64 | + - **Solid arrows** for agent-to-agent handoffs. |
| 65 | + - **Dotted arrows** for tool invocations. |
| 66 | +- An **end node** (`__end__`) indicating where execution terminates. |
| 67 | + |
| 68 | +## Customizing the Graph |
| 69 | + |
| 70 | +### Showing the Graph |
| 71 | +By default, `draw_graph` displays the graph inline. To show the graph in a separate window, write the following: |
| 72 | + |
| 73 | +```python |
| 74 | +draw_graph(triage_agent).view() |
| 75 | +``` |
| 76 | + |
| 77 | +### Saving the Graph |
| 78 | +By default, `draw_graph` displays the graph inline. To save it as a file, specify a filename: |
| 79 | + |
| 80 | +```python |
| 81 | +draw_graph(triage_agent, filename="agent_graph.png") |
| 82 | +``` |
| 83 | + |
| 84 | +This will generate `agent_graph.png` in the working directory. |
| 85 | + |
| 86 | + |
0 commit comments