# Agent Configuration UI - Design Prototype

## Overview
The Agent Configuration UI allows users to create, view, and manage Agent Types - the templates from which agent instances are spawned. This is a critical administrative interface for defining how AI agents behave, what models they use, and what permissions they have.

## User Stories
- As an admin, I want to create new agent types so I can define specialized AI agents for my projects
- As an admin, I want to configure model selection and parameters to optimize agent performance
- As an admin, I want to define MCP permissions to control what tools agents can access
- As an admin, I want to craft personality prompts to shape agent behavior and communication style
- As an admin, I want to view all agent types and their status at a glance
- As an admin, I want to duplicate existing agent types as starting points for new ones

## Key Screens

### 1. Agent Type List View
- Grid layout of agent type cards
- Search functionality
- Status filter (Active, Draft, Inactive)
- Create new agent type button
- Card shows: name, description, expertise tags, model, instance count, status

### 2. Agent Type Detail View
- Full configuration display (read-only)
- Description and expertise areas
- Model configuration (primary, failover, parameters)
- MCP permissions with scopes
- Personality prompt display
- Instance count and quick actions
- Duplicate, Edit, Delete buttons
- Danger zone for destructive actions

### 3. Agent Type Editor View
- Tabbed interface for organized editing:
  - **Basic Info**: Name, description, status, expertise areas
  - **Model**: Primary/failover model selection, temperature, max tokens, top P
  - **Permissions**: MCP server toggles with granular scope checkboxes
  - **Personality**: Large textarea for personality prompt with character count

## User Flow

### Creating a New Agent Type
1. User clicks "Create Agent Type" from list view
2. Editor opens with blank form
3. User fills in basic info (name, description, expertise)
4. User selects model configuration
5. User enables MCP permissions and selects scopes
6. User writes personality prompt
7. User saves (creates as Draft or Active)

### Editing an Existing Agent Type
1. User clicks agent type card in list
2. Detail view shows full configuration
3. User clicks "Edit" button
4. Editor opens with pre-filled data
5. User modifies settings across tabs
6. User saves changes

### Duplicating an Agent Type
1. User opens detail view
2. User clicks "Duplicate"
3. Editor opens with copied data and new name
4. User modifies as needed
5. User saves as new agent type

## Design Decisions

### Three-View Architecture
- **List**: Overview and discovery
- **Detail**: Read-only inspection
- **Editor**: Focused editing experience
- Clear navigation between views with back button

### Tabbed Editor
- Logical grouping of related settings
- Reduces cognitive load
- Allows focused work on one aspect at a time
- Icons on tabs for quick recognition

### Card-Based List
- Visual grid layout for quick scanning
- Status badges for instant status recognition
- Expertise tags show capabilities at a glance
- Instance count indicates usage

### MCP Permissions UI
- Checkbox for enabling/disabling each server
- Nested scopes only shown when server is enabled
- Clear visual distinction between enabled/disabled
- Granular control over what agents can access

### Model Configuration
- Primary + failover model selection
- Common parameters exposed (temperature, max tokens, top P)
- Helpful descriptions for each parameter
- Sensible defaults pre-filled

## States

### Loading
- Skeleton cards in list view
- Skeleton placeholders in detail/editor views

### Empty
- No agent types: "Create your first agent type" CTA
- No search results: "No agent types found" with suggestion

### Error
- Failed to load: Error card with retry button
- Failed to save: Toast notification with error details

### Validation
- Required fields highlighted
- Character limits enforced
- Model parameter ranges validated

## Responsive Breakpoints

### Desktop (lg: 1024px+)
- 3-column card grid in list view
- 2/3 + 1/3 split in detail view
- Full tab navigation visible

### Tablet (md: 768px)
- 2-column card grid
- Stacked layout in detail view
- Compact tab labels

### Mobile (< 768px)
- Single column card list
- Full-width cards
- Scrollable tab navigation
- Stacked form fields

## Accessibility Notes
- Form labels properly associated with inputs
- Tab panel navigation is keyboard accessible
- Status badges have text (not just color)
- Focus management when navigating between views
- Screen reader announces view changes
- Textarea has proper aria-labels

## Components Used
- Card, CardHeader, CardTitle, CardContent, CardDescription
- Button (default, outline, ghost, destructive variants)
- Badge (default, secondary, outline variants)
- Input, Textarea, Label
- Select, SelectContent, SelectItem, SelectTrigger, SelectValue
- Tabs, TabsList, TabsTrigger, TabsContent
- Checkbox
- Separator
- Lucide icons

## Form Fields Reference

### Basic Info
| Field | Type | Required | Validation |
|-------|------|----------|------------|
| Name | Text | Yes | 3-50 characters |
| Status | Select | Yes | active/draft/inactive |
| Description | Textarea | Yes | 10-500 characters |
| Expertise | Tags | No | Comma-separated |

### Model Configuration
| Field | Type | Required | Validation |
|-------|------|----------|------------|
| Primary Model | Select | Yes | From available models |
| Failover Model | Select | No | From available models |
| Temperature | Number | Yes | 0.0 - 2.0 |
| Max Tokens | Number | Yes | 1024 - 32768 |
| Top P | Number | Yes | 0.0 - 1.0 |

### MCP Permissions
| Server | Scopes |
|--------|--------|
| Gitea | read, write, issues, branches, prs |
| Knowledge Base | read, write |
| Filesystem | read, write |
| Slack | read, write |
| Jira | read, write, issues |

### Personality Prompt
- Large textarea (15 rows)
- Character count display
- Template insertion button
- Preview functionality

## Questions for Review
1. Should we add a "Test Agent" feature to try the personality prompt?
2. Is the tabbed editor the right approach or should all fields be on one page?
3. Should expertise be free-form tags or a predefined list?
4. Should model parameters have "presets" (conservative, balanced, creative)?
5. How should we handle versioning of agent types?
6. Should there be an approval workflow for activating agent types?

## How to View
Navigate to: `/prototypes/agent-configuration`

Click through the views:
1. Start on list view
2. Click any card to see detail view
3. Click "Edit" to see editor view
4. Click "Create Agent Type" to see editor in create mode

## Next Steps
After approval:
1. Implement form validation with react-hook-form and zod
2. Connect to agent type CRUD API
3. Add real model list from API
4. Implement tag input component for expertise
5. Add personality prompt templates
6. Implement MCP permission verification
7. Add loading skeletons and error states
