Organization Chart

Visual hierarchy of all agents — reporting structure, status indicators, and interactive tree layout on a zoomable canvas.

Overview

The Organization Chart renders a top-down tree layout of all agents in your organization. Each agent is a card node showing name, role, state, and activity badges. Edges (SVG curved paths) connect agents to their managers, forming a visual reporting hierarchy.

Key features:

• Automatic tree layout with top-down hierarchy
• Color-coded state indicators (running, stopped, error, paused)
• External (human) manager support with purple styling
• Interactive zoom, pan, and hover highlighting
• Summary metrics bar
• Rich hover tooltips with agent details

How It Works

1. Fetch data — Two API calls: /hierarchy/org-chart for hierarchy data, and /agents for avatars and metadata.
2. Build tree — Agents are grouped by managerId. Agents without a manager (or with an unresolvable manager) become root nodes.
3. External managers — Agents with managerType: 'external' are grouped under synthetic purple nodes representing human managers.
4. Compute layout — A recursive algorithm calculates subtree widths, then positions nodes top-down with even spacing (220×72px nodes, 40px horizontal gap, 80px vertical gap).
5. Render — SVG cubic Bézier curves for edges, HTML div cards for nodes, all on a zoomable/pannable canvas.
6. Auto-fit — On first render, the canvas auto-zooms to fit all nodes in view.

Key Concepts

Agent States

Manager Types

• Internal — Reports to another AI agent in the system
• External — Reports to a human manager (shown as a purple node)
• None — Root-level agent with no manager

Canvas Interactions

Node Cards

Each agent node (220×72px) displays:

• Avatar — Agent avatar image or colored initial circle with state-colored border
• State dot — Small circle at bottom-right of avatar showing current state
• Name — Agent name (truncated with ellipsis if too long)
• Role — Agent role description
• Badges:
  • MGR — Agent is a manager (has subordinates)
  • N tasks — Count of active tasks
  • N err — Errors today

Summary Metrics

Below the toolbar, a compact metrics bar shows:

• Agents — Total count (excluding external managers)
• Running — Active agents (green)
• Stopped — Inactive agents (gray, shown only if > 0)
• Error — Agents in error state (red, shown only if > 0)
• Paused — Paused agents (amber, shown only if > 0)
• Human — External manager nodes (purple, shown only if > 0)
• Managers — Agents with subordinates
• Active Tasks — Total across all agents
• Errors Today — Total errors across all agents

Hover Tooltip

Hovering over any node shows a fixed-position tooltip with:

• Agent avatar, name, and role
• Current state
• Clocked-in status (Yes/No)
• Type (Internal AI / External Human)
• Reports to (manager name)
• Direct reports count
• Active tasks count
• Errors today count
• Last active timestamp (relative, e.g., "5m ago")

External Managers

When agents have managerType: 'external' with a managerName and/or managerEmail, the system creates synthetic purple nodes representing human managers. These nodes:

• Use a purple gradient avatar
• Show "External Manager" as role
• Group all agents reporting to that human under a single node
• Are always shown as the root of their subtree

Configuration & Setup

Setting Up the Hierarchy

The org chart automatically reflects agent configurations. To create hierarchy:

1. Set managerId on agent config to point to another agent's ID for internal reporting
2. Or set managerType: 'external' with externalManagerName and externalManagerEmail for human managers
3. Agents without a manager appear as root nodes

Agent Avatars

Avatars are resolved from (in priority order):

1. config.identity.avatar
2. config.avatar
3. config.persona.avatar

If none is set, a colored circle with the first letter of the agent's name is shown.

API Reference

Org Chart Node Fields

Best Practices

• Define clear reporting lines: Set managerId on every agent to create a clean hierarchy. Orphan agents cluster at the root level.
• Use external managers: If humans oversee AI agents, set them as external managers for a complete picture.
• Monitor error badges: Red error badges on nodes indicate agents needing attention — investigate promptly.
• Keep teams balanced: If one manager agent has 20+ direct reports, consider adding intermediate management layers.
• Set avatars: Custom avatars make the chart much easier to scan visually, especially with large teams.
• Use Fit to View: After making hierarchy changes, click "Fit" to re-center the chart.

Troubleshooting

Related Pages