JAF Graphviz Visualization¶

The JAF (Juspay Agent Framework) visualization module provides powerful graph generation capabilities for visualizing agents, tools, and runner architectures. The system now uses direct DOT generation instead of the graphviz npm package, providing better reliability and performance.

Overview¶

Purpose and Capabilities¶

The JAF Graphviz visualization system provides:

Agent Architecture Visualization: Generate comprehensive diagrams showing agent relationships, tool connections, and sub-agent hierarchies
Tool Network Graphs: Create visual representations of tool ecosystems and dependencies
Runner Architecture Diagrams: Visualize complete runner configurations including session providers and execution flows
Multiple Output Formats: Support for PNG, SVG, and PDF output formats
Customizable Styling: Three built-in color schemes (default, modern, minimal) with full customization options
Functional Design: Pure functional implementation following JAF's architectural principles

What Can Be Visualized¶

Agents: Main agents with their configurations, models, and metadata
Sub-agents: Hierarchical agent relationships and delegation flows
Tools: Tool definitions, parameters, and connections to agents
Runner Configurations: Complete system architecture including session management
Execution Flows: Visual representation of how components interact

Installation¶

System Requirements¶

Node.js 16+ with TypeScript support
Graphviz system installation (for PNG/SVG/PDF generation)
JAF framework installed and configured

Graphviz Installation Steps¶

macOS (using Homebrew):

brew install graphviz

Ubuntu/Debian:

sudo apt-get update
sudo apt-get install graphviz

Windows:

# Using Chocolatey
choco install graphviz

# Or download from: https://graphviz.org/download/

Verify Installation:

dot -V
# Should output: dot - graphviz version X.X.X

npm Package Setup¶

The visualization module is included with JAF and uses the graphviz npm package:

{
  "dependencies": {
    "graphviz": "^0.0.9"
  },
  "devDependencies": {
    "@types/graphviz": "^0.0.39"
  }
}

API Reference¶

Core Functions¶

`generateAgentGraph(agents, options?)`¶

Generates a graph visualization of one or more agents and their relationships.

Parameters: - agents: readonly Agent[] - Array of agents to visualize - options?: GraphOptions - Optional configuration options

Returns: Promise<GraphResult>

Example:

import { generateAgentGraph } from 'jaf/visualization';

const result = await generateAgentGraph([agent1, agent2], {
  title: 'My Agent System',
  outputFormat: 'png',
  colorScheme: 'modern'
});

`generateToolGraph(tools, options?)`¶

Creates a visualization of tools and their relationships.

Parameters: - tools: readonly Tool[] - Array of tools to visualize - options?: GraphOptions - Optional configuration options

Returns: Promise<GraphResult>

`generateRunnerGraph(config, options?)`¶

Generates a comprehensive runner architecture diagram.

Parameters: - config: RunnerConfig - Runner configuration to visualize - options?: GraphOptions - Optional configuration options

Returns: Promise<GraphResult>

`generateRunnerGraphPng(config, outputPath?)`¶

Convenience function for generating PNG runner visualizations.

Parameters: - config: RunnerConfig - Runner configuration - outputPath?: string - Output file path (without extension)

Returns: Promise<GraphResult>

Configuration Options¶

`GraphOptions` Interface¶

interface GraphOptions {
  readonly title?: string;           // Graph title
  readonly layout?: 'dot' | 'neato' | 'fdp' | 'circo' | 'twopi';
  readonly rankdir?: 'TB' | 'LR' | 'BT' | 'RL';  // Direction
  readonly outputFormat?: 'png' | 'svg' | 'pdf'; // Output format
  readonly outputPath?: string;      // Output file path
  readonly showToolDetails?: boolean; // Include tool information
  readonly showSubAgents?: boolean;   // Include sub-agents
  readonly colorScheme?: 'default' | 'modern' | 'minimal';
}

Layout Options: - dot: Hierarchical layouts (default for agents/runners) - neato: Spring model layouts - fdp: Force-directed placement - circo: Circular layout (default for tools) - twopi: Radial layouts

Direction Options: - TB: Top to Bottom (default) - LR: Left to Right - BT: Bottom to Top - RL: Right to Left

Result Structure¶

`GraphResult` Interface¶

interface GraphResult {
  readonly success: boolean;    // Whether generation succeeded
  readonly outputPath?: string; // Path to generated file
  readonly error?: string;      // Error message if failed
  readonly graphDot?: string;   // Generated DOT content
}

Visualization Types¶

Agent Graphs¶

Agent graphs show the relationships between agents, their tools, and sub-agents:

import { generateAgentVisualization } from 'jaf/adk/runners';

const agents = [mainAgent, helperAgent];
const result = await generateAgentVisualization(agents, {
  title: 'Agent Network',
  showToolDetails: true,
  showSubAgents: true,
  colorScheme: 'modern'
});

Features: - Agent nodes with model information and tool counts - Tool connections showing available capabilities - Sub-agent relationships with delegation flows - Hierarchical layout showing system structure

Tool Graphs¶

Tool graphs visualize tool ecosystems and their relationships:

import { generateToolVisualization } from 'jaf/adk/runners';

const tools = [calculatorTool, weatherTool, searchTool];
const result = await generateToolVisualization(tools, {
  title: 'Tool Ecosystem',
  layout: 'circo',
  colorScheme: 'default'
});

Features: - Tool nodes with descriptions and metadata - Circular layout for clear tool overview - Color-coded by tool source (function, API, etc.) - Parameter information display

Runner Architecture¶

Runner visualizations show complete system architecture:

import { generateRunnerGraphPng } from 'jaf/adk/runners';

const runnerConfig = createRunnerConfig(agent, sessionProvider);
const result = await generateRunnerGraphPng(runnerConfig, './architecture');

Features: - Runner execution flow - Session provider integration - Agent and tool relationships - Sub-agent delegation paths - System boundaries and clusters

Color Schemes¶

Default Scheme¶

Professional blue-purple color palette suitable for technical documentation:

Agents: Light blue background (#E3F2FD) with blue text (#1976D2)
Tools: Light purple background (#F3E5F5) with purple text (#7B1FA2)
Sub-agents: Light green background (#E8F5E8) with green text (#388E3C)
Edges: Dark gray (#424242) with solid lines

Modern Scheme¶

Contemporary gradient-style colors for presentations:

Agents: Blue gradient (#667eea) with white text and bold fonts
Tools: Pink gradient (#f093fb) with white text
Sub-agents: Light blue (#4facfe) with white text
Edges: Blue (#667eea) with enhanced arrow styles

Minimal Scheme¶

Clean, minimalist black-and-white design:

Agents: White background with black text and bold borders
Tools: Light gray background (#f5f5f5) with black text
Sub-agents: White background with gray text
Edges: Black with simple styling

Customization Options¶

You can extend color schemes by modifying the COLOR_SCHEMES configuration:

// Custom color scheme example
const customScheme = {
  agent: { 
    shape: 'box', 
    fillcolor: '#your-color', 
    fontcolor: 'white', 
    style: 'filled,rounded' 
  },
  tool: { 
    shape: 'ellipse', 
    fillcolor: '#tool-color', 
    fontcolor: 'black', 
    style: 'filled' 
  },
  // ... other style definitions
};

Usage Examples¶

Quick Start¶

Generate a basic agent visualization:

import { quickStartVisualization } from 'jaf/visualization';

const agent = createAgent({
  name: 'My Assistant',
  model: 'gpt-4',
  tools: [calculatorTool, weatherTool]
});

await quickStartVisualization(agent, './my-agent-graph');

Advanced Configuration¶

Create a comprehensive system visualization:

import { 
  generateAgentVisualization, 
  generateRunnerGraphPng 
} from 'jaf/adk/runners';

// Multi-agent system
const agents = [
  primaryAgent,
  mathSpecialist,
  researchAgent
];

const agentResult = await generateAgentVisualization(agents, {
  title: 'Multi-Agent System Architecture',
  outputPath: './system-overview',
  outputFormat: 'svg',
  layout: 'dot',
  rankdir: 'LR',
  showToolDetails: true,
  showSubAgents: true,
  colorScheme: 'modern'
});

// Runner architecture
const runnerConfig = createRunnerConfig(primaryAgent, sessionProvider);
const runnerResult = await generateRunnerGraphPng(
  runnerConfig, 
  './runner-architecture'
);

Integration with Runners¶

Use visualization within runner lifecycle:

import { createRunner, generateRunnerGraphPng } from 'jaf/adk/runners';

const runner = createRunner(agent, sessionProvider);

// Generate architecture diagram
const vizResult = await generateRunnerGraphPng(
  runner.config,
  `./docs/architecture-${Date.now()}`
);

if (vizResult.success) {
  console.log(`Architecture diagram: ${vizResult.outputPath}`);
}

Batch Generation¶

Generate multiple visualizations:

import { runVisualizationExamples } from 'jaf/visualization';

// Generates complete example set:
// - Agent graphs with different color schemes
// - Tool ecosystem visualization
// - Runner architecture diagram
await runVisualizationExamples();

Error Handling¶

Robust error handling with fallbacks:

const result = await generateAgentVisualization(agents, options);

if (result.success) {
  console.log(`✅ Generated: ${result.outputPath}`);
} else {
  console.error(`❌ Failed: ${result.error}`);

  // DOT content is still available for manual processing
  if (result.graphDot) {
    console.log('DOT content available for manual generation');
    // Save DOT file for manual processing
    writeFileSync('./graph.dot', result.graphDot);
  }
}

Troubleshooting¶

Common Issues¶

"Graphviz not installed" Error¶

Problem: System Graphviz is not installed or not in PATH.

Solution:

# Install Graphviz
brew install graphviz  # macOS
sudo apt-get install graphviz  # Ubuntu/Debian
choco install graphviz  # Windows

# Verify installation
dot -V

"Process exited with code 1" Error¶

Problem: Graphviz process failed during generation.

Solutions: 1. Check file permissions for output directory 2. Verify output path is valid and writable 3. Ensure no special characters in file paths 4. Try different output format (PNG vs SVG)

Empty or Corrupted Output Files¶

Problem: Files are generated but appear empty or corrupted.

Solutions: 1. Check available disk space 2. Verify Graphviz version compatibility 3. Try simpler graph configurations 4. Use fallback DOT generation

Performance Issues with Large Graphs¶

Problem: Slow generation with many agents/tools.

Solutions: 1. Disable tool details: showToolDetails: false 2. Disable sub-agents: showSubAgents: false 3. Use simpler layouts: layout: 'neato' 4. Generate smaller subsets of the system

Fallback Mechanisms¶

The visualization system includes automatic fallbacks:

npm graphviz Package Issues: Falls back to system Graphviz command
System Graphviz Missing: Provides DOT content for manual processing
File Generation Errors: Returns error details with DOT content preserved

Debug Information¶

Enable verbose output for troubleshooting:

const result = await generateRunnerGraph(config, {
  title: 'Debug Visualization'
});

if (!result.success) {
  console.log('Error:', result.error);
  console.log('DOT Content Length:', result.graphDot?.length);

  // Save DOT for manual inspection
  if (result.graphDot) {
    writeFileSync('./debug.dot', result.graphDot);
    console.log('DOT file saved for manual processing');
  }
}

Manual DOT Processing¶

If automated generation fails, process DOT files manually:

# Generate PNG from DOT
dot -Tpng input.dot -o output.png

# Generate SVG from DOT
dot -Tsvg input.dot -o output.svg

# Generate PDF from DOT
dot -Tpdf input.dot -o output.pdf

System Requirements Check¶

Verify your environment meets requirements:

import { execSync } from 'child_process';

try {
  const version = execSync('dot -V', { encoding: 'utf8' });
  console.log('Graphviz available:', version);
} catch (error) {
  console.log('Graphviz not found - install required');
}

Getting Help¶

For additional support:

Check the JAF GitHub repository for issues
Review the examples in /examples/server-demo/test-runner-visualization.ts
Use the built-in validation: validateGraphOptions(options)
Enable debug output in your runner configuration

JAF Graphviz Visualization¶

Table of Contents¶

Overview¶

Purpose and Capabilities¶

What Can Be Visualized¶

Installation¶

System Requirements¶

Graphviz Installation Steps¶

npm Package Setup¶

API Reference¶

Core Functions¶

generateAgentGraph(agents, options?)¶

generateToolGraph(tools, options?)¶

generateRunnerGraph(config, options?)¶

generateRunnerGraphPng(config, outputPath?)¶

Configuration Options¶

GraphOptions Interface¶

Result Structure¶

GraphResult Interface¶

Visualization Types¶

Agent Graphs¶

Tool Graphs¶

Runner Architecture¶

Color Schemes¶

Default Scheme¶

Modern Scheme¶

Minimal Scheme¶

Customization Options¶

Usage Examples¶

Quick Start¶

Advanced Configuration¶

Integration with Runners¶

Batch Generation¶

Error Handling¶

Troubleshooting¶

Common Issues¶

"Graphviz not installed" Error¶

"Process exited with code 1" Error¶

Empty or Corrupted Output Files¶

Performance Issues with Large Graphs¶

Fallback Mechanisms¶

Debug Information¶

Manual DOT Processing¶

System Requirements Check¶

Getting Help¶

Related Documentation¶

`generateAgentGraph(agents, options?)`¶

`generateToolGraph(tools, options?)`¶

`generateRunnerGraph(config, options?)`¶

`generateRunnerGraphPng(config, outputPath?)`¶

`GraphOptions` Interface¶

`GraphResult` Interface¶