agentgraphgenerator.go

Overview

The agentgraphgenerator.go file is responsible for generating a visual graph representation of agents and their relationships within the system. It uses the gographviz library to construct directed graphs depicting agents, their sub-agents, tools they incorporate, and their interaction structure. The generated graph is designed to highlight agent clusters (composite agents composed of sub-agents), indicate agent and tool types through node shapes and captions, and visually emphasize specified nodes or edges.

This visualization supports understanding the hierarchical and interaction structure of AI agents, including special cluster agents such as sequential, loop, and parallel agents that orchestrate complex workflows. The primary output is a graph description in DOT language format, suitable for rendering with Graphviz-compatible tools.

Key Concepts and Components

Supported Cluster Agents

The file defines a list of supported cluster agent types:

• TypeLoopAgent

• TypeSequentialAgent

• TypeParallelAgent

These special agent types are responsible for complex orchestration patterns such as looping through sub-agents, sequential execution, or parallel execution of sub-agents.

Named Instances

The interface namedInstance requires a single method:

type namedInstance interface {
    Name() string
}

This abstraction is used to generically handle agents and tools by their names.

Functions and Methods

nodeName(instance any) string

Returns the name of the given instance, which may be either an agent.Agent or a tool.Tool. If the instance type is unknown, it returns "Unknown instance type".

Parameters:

• instance any: The object to get the name from (agent or tool).

Returns:

• string: The name of the instance.

nodeCaption(instance any) string

Generates a caption label for graph nodes representing the instance. It prepends an emoji based on the type (robot for agent, wrench for tool). For supported cluster agents, it appends the agent type in parentheses.

Parameters:

• instance any: The agent or tool instance.

Returns:

• string: Quoted caption string for use as a node label.

nodeShape(instance any) string

Determines the Graphviz shape attribute for nodes, based on instance type:

• Agents → "ellipse"

• Tools → "box"

• Others → "cylinder"

Parameters:

• instance any: The instance for which the node shape is determined.

Returns:

• string: The Graphviz shape type.

shouldBuildAgentCluster(instance any) bool

Checks if the given instance is a cluster agent type that should be drawn as a subgraph cluster.

Parameters:

• instance any: Expected to be an agent.

Returns:

• bool: true if the instance is a supported cluster agent; false otherwise.

highlighted(nodeName string, highlightedPairs [][]string) bool

Determines whether a node should be highlighted based on its presence in any of the provided pairs.

Parameters:

• nodeName string: Name of the node.

• highlightedPairs [][]string: List of node name pairs that indicate highlighting.

Returns:

• bool: true if the node is part of any highlight pair; false otherwise.

edgeHighlighted(from, to string, highlightedPairs [][]string) *bool

Checks if an edge between two nodes should be highlighted, considering directionality. Returns a pointer to a boolean indicating:

• nil: no highlight

• true: highlight in from -> to direction

• false: highlight in reversed direction to -> from

Parameters:

• from string: Source node name.

• to string: Destination node name.

• highlightedPairs [][]string: List of node pairs defining highlighted edges.

Returns:

• *bool: Pointer to highlight status or nil.

drawCluster(parentGraph, cluster *gographviz.Graph, agent agent.Agent, highlightedPairs [][]string, visitedNodes map[string]bool) error

Builds a subgraph cluster for a composite agent (cluster agent). It recursively processes sub-agents, draws their nodes and edges according to agent type:

• Sequential agents connect sub-agents linearly.

• Loop agents connect sub-agents in a circular manner.

• Parallel agents do not connect sub-agents directly.

Parameters:

• parentGraph *gographviz.Graph: The main graph.

• cluster *gographviz.Graph: The subgraph cluster being created.

• agent agent.Agent: The cluster agent.

• highlightedPairs [][]string: Highlighted node/edge pairs.

• visitedNodes map[string]bool: Tracker for nodes already processed.

Returns:

• error: Any error encountered during graph construction.

drawNode(graph, parentGraph *gographviz.Graph, instance any, highlightedPairs [][]string, visitedNodes map[string]bool) error

Draws a node in the graph for the given instance. If the instance is a cluster agent, it creates a subgraph cluster and delegates drawing to drawCluster. Otherwise, it adds a single node with appropriate attributes including highlighting.

Parameters:

• graph *gographviz.Graph: The current graph or cluster.

• parentGraph *gographviz.Graph: The root parent graph.

• instance any: Agent or tool instance.

• highlightedPairs [][]string: Highlighted nodes/edges.

• visitedNodes map[string]bool: Tracks visited nodes to avoid duplication.

Returns:

• error: Error if node/cluster creation fails.

drawEdge(graph *gographviz.Graph, from, to string, highlightedPairs [][]string) error

Adds a directed edge from from node to to node with attributes indicating highlight status and arrow style.

Parameters:

• graph *gographviz.Graph: Graph to which the edge is added.

• from string: Source node name.

• to string: Destination node name.

• highlightedPairs [][]string: Highlighted edge pairs.

Returns:

• error: If edge addition fails.

buildGraph(graph, parentGraph *gographviz.Graph, instance any, highlightedPairs [][]string, visitedNodes map[string]bool) error

Recursively constructs the graph starting from the root instance. It draws the node or cluster, adds nodes for tools (for LLM agents), connects agent to tools via edges, and recursively processes sub-agents.

Parameters:

• graph *gographviz.Graph: Current graph or cluster context.

• parentGraph *gographviz.Graph: Parent graph for adding nodes/clusters.

• instance any: Agent or tool instance to draw.

• highlightedPairs [][]string: Node and edge highlights.

• visitedNodes map[string]bool: Tracks which nodes are already visited to avoid cycles.

Returns:

• error: Any error encountered during graph construction.

GetAgentGraph(ctx context.Context, agent agent.Agent, highlightedPairs [][]string) (string, error)

Entry point to generate the graph of an agent. It initializes the graph with attributes (name, direction, background color), invokes buildGraph to recursively construct the agent graph, and returns the graph in DOT format as a string.

Parameters:

• ctx context.Context: Execution context.

• agent agent.Agent: Root agent to graph.

• highlightedPairs [][]string: List of node pairs to highlight.

Returns:

• string: DOT language representation of the graph.

• error: Any error during graph generation.

Example Usage:

dotGraph, err := GetAgentGraph(ctx, myAgent, [][]string{{"AgentA", "ToolX"}})
if err != nil {
    log.Fatal(err)
}
// dotGraph now contains the DOT format of the agent graph.

Implementation Details and Algorithms

• The graph uses cluster subgraphs (gographviz subgraphs) to represent composite (cluster) agents, visually grouping their sub-agents.

• The recursive buildGraph function uses a visitedNodes map to prevent infinite recursion and duplicate nodes.

• Highlighting is performed by checking if nodes or edges are in the highlightedPairs list, changing colors and styles accordingly.

• Edges in sequential and loop agents are drawn to enforce their execution order (linear or circular).

• Tools associated with LLM agents are visualized as nodes connected to the agent node.

• The use of interface type assertions allows generic handling of agents and tools without explicit type coupling.

• Constants define color values for consistent graph styling.

Interaction with Other System Components

• This file depends on the agent.Agent interface and internal agent types from agentinternal and llmagentinternal packages. These provide access to sub-agents, tools, and metadata such as agent types.

• The gographviz library is used to create and manipulate Graphviz DOT graphs.

• The generated graph output can be consumed by visualization tools or exported for debugging, documentation, or UI display purposes.

• Highlighting functionality supports integration with UI components or diagnostics that indicate important nodes or paths.

• This code complements the agent workflow management by providing a visual representation of agent orchestration strategies described in Agent Workflow Management.

Mermaid Diagram: Structure of agentgraphgenerator.go

classDiagram
class agentgraphgenerator {
+GetAgentGraph()
-buildGraph()
-drawNode()
-drawCluster()
-drawEdge()
-nodeName()
-nodeCaption()
-nodeShape()
-shouldBuildAgentCluster()
-highlighted()
-edgeHighlighted()
-boolPtr()
}
agentgraphgenerator ..> gographviz.Graph : uses
agentgraphgenerator ..> agent.Agent : uses
agentgraphgenerator ..> tool.Tool : uses

This documentation details the functional components and usage of the agentgraphgenerator.go file, focusing on generating hierarchical visual graphs of agents and their subcomponents with contextual highlights. For further context on agent types and workflows, see [Agent Workflow Management](80558) and [LLM Integration and Agents](80562).