components/agents/ — Agent UI Components

Contents

Architecture

flowchart TD
  AM["AgentsMenu\n(State machine root)"] --> AL["AgentsList\n(Browse by source)"]
  AM --> AD["AgentDetail\n(Read-only view)"]
  AM --> AE["AgentEditor\n(Edit tools/color/model)"]
  AM --> CW["CreateAgentWizard\n(Multi-step creation)"]
  AM --> DC["Delete Confirm\n(Confirmation dialog)"]

  AE --> TS["ToolSelector\n(5 tool buckets)"]
  AE --> CP["ColorPicker\n(Agent colors)"]
  AE --> MS["ModelSelector\n(Claude models)"]

  CW --> LS["LocationStep"]
  CW --> MTS["MethodStep"]
  CW --> GS["GenerateStep\n(AI generation)"]
  CW --> TYS["TypeStep"]
  CW --> PS["PromptStep"]
  CW --> DS["DescriptionStep"]
  CW --> CS["ConfirmStep"]

  GS --> GA["generateAgent()\n(Claude API call)"]

Key Classes & Functions

Data Structures

Interactions

State Machine

stateDiagram-v2
  [*] --> main_menu
  main_menu --> list_agents: Select source
  list_agents --> agent_menu: Select agent
  list_agents --> create_agent: Create new
  agent_menu --> view_agent: View details
  agent_menu --> edit_agent: Edit agent
  agent_menu --> delete_confirm: Delete agent
  view_agent --> agent_menu: Back
  edit_agent --> agent_menu: Save/Cancel
  delete_confirm --> list_agents: Confirmed
  delete_confirm --> agent_menu: Cancelled
  create_agent --> list_agents: Completed

Configuration

Directory Map

components/agents/
├── AgentsMenu.tsx              ← State machine root: mode dispatch and coordination
├── AgentsList.tsx              ← Browsable list grouped by source (user/project/built-in)
├── AgentDetail.tsx             ← Read-only agent profile view
├── AgentEditor.tsx             ← Edit agent tools, color, model via sub-menus
├── AgentNavigationFooter.tsx   ← Navigation hint footer (↑↓ Enter Esc)
├── ColorPicker.tsx             ← Interactive color selector with preview
├── ModelSelector.tsx           ← Claude model dropdown with descriptions
├── ToolSelector.tsx            ← 5-bucket tool picker (Read/Edit/Exec/MCP/Other)
├── types.ts                    ← ModeState union, AGENT_PATHS, validation types
├── utils.ts                    ← Display name helpers for agent sources
├── validateAgent.ts            ← Agent definition validation (type, prompt, tools)
├── agentFileUtils.ts           ← File I/O: save, update, delete, format as markdown
├── generateAgent.ts            ← AI-powered agent generation via Claude API
└── new-agent-creation/
    ├── CreateAgentWizard.tsx    ← 11-step wizard orchestrator
    └── wizard-steps/
        ├── TypeStep.tsx         ← Agent identifier input with validation
        ├── LocationStep.tsx     ← Source selection (user/project/local)
        ├── MethodStep.tsx       ← Manual vs AI-generated creation choice
        ├── GenerateStep.tsx     ← AI generation loading and result handling
        ├── PromptStep.tsx       ← System prompt editor
        ├── DescriptionStep.tsx  ← When-to-use description editor
        ├── ToolsStep.tsx        ← Tool selection via ToolSelector
        ├── ModelStep.tsx        ← Model selection via ModelSelector
        ├── ColorStep.tsx        ← Color selection via ColorPicker
        ├── MemoryStep.tsx       ← Memory scope configuration
        └── ConfirmStep.tsx      ← Review and save confirmation

Deep-Dive Highlights

Core mechanisms from this sub-module have been extracted into dedicated focus pages for in-depth exploration.

Deep-Dive Pages

Creation Wizard Steps

Validation Rules

Agent Sources

Agents can be defined in multiple locations with override precedence:

Code Examples

Example: Agent Validation

// Validates an agent definition before saving
const result = validateAgent(
  {
    agentType: 'code-reviewer',
    whenToUse: 'Use when reviewing pull requests for bugs and style issues',
    systemPrompt: 'You are an expert code reviewer. Focus on correctness, security...',
    tools: ['FileRead', 'Grep', 'Glob'],
  },
  availableTools,
  existingAgents,
);

if (!result.isValid) {
  result.errors.forEach(err => console.error(err));
}
result.warnings.forEach(warn => console.warn(warn));

Example: Tool Bucket Categorization

// Tools are organized into 5 buckets for the selector UI
const buckets: ToolBuckets = {
  READ_ONLY: {
    name: 'Read-only',
    toolNames: new Set(['FileRead', 'Grep', 'Glob', 'LSP']),
  },
  EDIT: {
    name: 'Edit',
    toolNames: new Set(['FileEdit', 'FileWrite', 'NotebookEdit']),
  },
  EXECUTION: {
    name: 'Execution',
    toolNames: new Set(['Bash', 'WebFetch', 'WebSearch']),
  },
  MCP: {
    name: 'MCP Tools',
    toolNames: getMcpServerBuckets(tools),
    isMcp: true,
  },
  OTHER: {
    name: 'Other',
    toolNames: new Set(['Agent', 'TaskOutput']),
  },
};

Example: Agent File Format (Markdown with YAML)

// formatAgentAsMarkdown() produces this format for agent files:
function formatAgentAsMarkdown(
  agentType: string,
  whenToUse: string,
  tools: string[] | undefined,
  systemPrompt: string,
  color?: string,
  model?: string,
): string {
  const lines: string[] = [
    '---',
    `agent: ${agentType}`,
  ];

  if (tools) {
    lines.push('tools:');
    tools.forEach(t => lines.push(`  - ${t}`));
  }
  if (color) lines.push(`color: ${color}`);
  if (model) lines.push(`model: ${model}`);

  lines.push('---', '', `# ${agentType}`, '');
  lines.push('## When to use', '', whenToUse, '');
  lines.push('## System prompt', '', systemPrompt);

  return lines.join('\n');
}