Agent Roster

Install

npx ax-depute@latest add agent-roster

pnpm dlx ax-depute@latest add agent-roster

yarn dlx ax-depute@latest add agent-roster

bunx ax-depute@latest add agent-roster

A dense table view designed for the "Flat Swarm" orchestration model (e.g., OpenAI's Swarm). It allows a human supervisor to scan 20+ concurrent workers at a glance, monitoring roll-up metrics like agent status, uptime, and token cost.

Agent	Current Task	Tokens	Last Active
Orchestrator-PrimeOrchestrator	Running lint and formatting checks on new files	33,833	6m ago
Researcher-AResearcher	Validating output against business rules	20,601	2m ago
Code-Writer-1Code Writer	Writing unit tests for the payment module	10,197	6m ago
Code-Writer-2QA Inspector	—	20,124	9m ago

Interactive StorybookView all states, toggle props, and test edge cases.

Basic usage

import { useState } from 'react';
import { AgentRoster } from '@/components/AgentRoster';
import type { AgentRosterItem } from '@/components/AgentRoster/AgentRoster.types';

const mockAgents: AgentRosterItem[] = [
  {
    id: 'ag_1',
    name: 'Research Router',
    role: 'Orchestrator',
    status: 'working',
    currentTask: 'Delegating to search APIs',
    tokensUsed: 1250,
    lastActive: 'Just now'
  },
  {
    id: 'ag_2',
    name: 'Browser Node',
    role: 'Web Scraper',
    status: 'failed',
    currentTask: 'Scraping Wikipedia',
    tokensUsed: 840,
    lastActive: '5m ago'
  }
];

export function App() {
  const [selectedId, setSelectedId] = useState<string>('ag_1');

  return (
    <div className="p-4 border border-zinc-200 dark:border-zinc-800 rounded-lg">
      <AgentRoster 
        agents={mockAgents}
        selectedAgentId={selectedId}
        onAgentSelect={(agent) => setSelectedId(agent.id)}
      />
    </div>
  );
}

Props

Prop	Type	Default	Description
`agents`	`AgentRosterItem[]`	`undefined`	Array of agent data objects to render as rows in the table.
`selectedAgentId`	`string`	`undefined`	The `id` of the currently selected agent row.
`onAgentSelect`	`(agent: AgentRosterItem) => void`	`undefined`	Callback fired when the user clicks on a row.
`className`	`string`	`undefined`	Additional CSS class for the root element.

Types

`AgentRosterItem`

import type { AgentStatus } from '../OrchestratorView/OrchestratorView.types';

export interface AgentRosterItem {
  id: string;
  name: string;
  role: string;
  status: AgentStatus;          // 'idle' | 'working' | 'blocked' | 'failed' | 'completed'
  currentTask?: string;         // E.g., "Summarizing PDF"
  tokensUsed?: number;          // Token burn count for this session
  lastActive?: string;          // E.g., "2m ago"
}

Composition flow

Agent Roster is specifically designed for flat worker pools.

Use it alongside Swarm Monitor at the top of the viewport to provide aggregate cost and error metrics for the entire fleet.
When a user clicks a specific row (onAgentSelect), surface the detail view for that agent using a combination of Plan Card, Tool Trace, and Run Controls.

Design rationale

1. Data Density for Flat Swarms
While Orchestrator View is best for hierarchical workflows, Agent Roster is designed for "flat" worker pools (like OpenAI Swarm). It prioritizes information density over structural mapping, allowing supervisors to monitor dozens of parallel tasks without scrolling.

2. Roll-Up Status Metrics
The header of the roster automatically calculates and displays summary metric pills based on the agents array (e.g., showing how many agents are Working, Blocked, or Failed). This provides instant situational awareness of the swarm's health.

3. Economic Visibility
Agents spend money. The tokensUsed column surfaces economic metrics directly into the operational view, treating API spend as a first-class citizen alongside task status and uptime.