diff --git a/docs/assets/images/graph.png b/docs/assets/images/graph.png new file mode 100644 index 0000000..13e2d6e Binary files /dev/null and b/docs/assets/images/graph.png differ diff --git a/docs/visualizations.md b/docs/visualizations.md new file mode 100644 index 0000000..2a8bb28 --- /dev/null +++ b/docs/visualizations.md @@ -0,0 +1,106 @@ +# 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 + +The visualization functionality relies on the **Graphviz** package. To use it, ensure you have Graphviz installed and add it as a dependency in `pyproject.toml`. Alternatively, install it directly via pip: + +```bash +pip install graphviz +``` + +## 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. +- **Tools** are represented as green ellipses. +- **Handoffs** are directed edges from one agent to another. + +### Example Usage + +```python +from agents import Agent, function_tool +from agents.visualizations 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", +) + +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], +) + +draw_graph(triage_agent) +``` + +![Agent Graph](./assets/images/graph.png) + +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. +- Directed edges indicating interactions: + - **Solid arrows** for agent-to-agent handoffs. + - **Dotted arrows** for tool invocations. +- An **end node** (`__end__`) indicating where execution terminates. + +## 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: + +```python +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: + +```python +draw_graph(triage_agent, filename="agent_graph.png") +``` + +This will generate `agent_graph.png` in the working directory. + +## Testing the Visualization + +The visualization functionality includes test coverage to ensure correctness. Tests are located in `tests/test_visualizations.py` and verify: + +- Node and edge correctness in `get_main_graph()`. +- Proper agent and tool representation in `get_all_nodes()`. +- Accurate relationship mapping in `get_all_edges()`. +- Graph rendering functionality in `draw_graph()`. + +Run tests using: + +```bash +pytest tests/test_visualizations.py +``` + +## Conclusion + +Agent visualization provides a powerful way to **understand, debug, and communicate** how agents interact within an application. By leveraging **Graphviz**, you can generate intuitive visual representations of complex agent structures effortlessly. + +For further details on agent functionality, see the [Agents documentation](agents.md). +