Managing Agents

​

Overview

​

Page Layout

​

Header Section

• Title: “Voice AI Agents”
• Icon: Bot icon (purple gradient background)
• Description: “Create and manage intelligent voice agents that can handle calls, provide support, and drive sales”

1. Active Agents Counter
   • Shows total number of active agents
   • Icon: Activity (pulse animation)
   • Real-time updates
2. Create Agent Button
   • Blue button with dropdown
   • Three options:
     • Pipeline Agent (Voice)
     • Realtime Agent (Voice)
     • Chat Agent (Text)

​

Main Content

• Title: “Your Voice Agents”
• Subtitle: “Manage, test, and iterate on your active voice agents”

• Responsive grid layout
• Auto-adjusts columns based on screen size:
  • Desktop (lg): 3 columns
  • Tablet (md): 2 columns
  • Mobile (sm): 1 column
• Cards have hover effects (shadow elevation)

​

Agent Card Details

​

Card Header

• Agent Icon (left)
  • Purple gradient background
  • Bot icon
  • Rounded square (48x48px)
• Agent Name (bold, large)
  • Truncated if too long
  • Clickable (leads to edit page)
• Description (below name)
  • Gray text
  • 2-line max (truncated with ellipsis)
  • Internal notes about agent purpose

• Trash icon
• Gray by default
• Turns red on hover
• Requires confirmation dialog

​

Card Body

• Voice (Pipeline) — Blue badge
• Voice (Realtime) — Purple badge
• Chat (Text) — Green badge

​

Card Footer (Actions)

1. Left Button (Primary Action):
   • If Agent Active: “Pause” button
     • Orange outline
     • Pause icon
     • Click to pause agent
   • If Agent Paused: “Try Now” button
     • Blue background
     • Play icon
     • Click to test agent
2. Right Button (Secondary Action):
   • “Edit” button
   • Gray outline
   • Hover: Dark background, white text
   • Leads to agent configuration page

​

Creating a New Agent

​

Step 1: Click “Create Agent”

• Blue background
• Plus icon
• Dropdown arrow
• Disabled if no organization selected

​

Step 2: Select Agent Type

​

Step 3: Agent Created

1. System creates agent with default settings:
   • Name: “New [Type] Agent”
   • Description: Auto-generated based on type
   • Architecture: Selected type
   • Default model: Gemini-2.0-flash
   • Default language: English
2. Redirects to agent configuration page
3. URL: /agents/create-agent/{agentId}

​

Testing an Agent

​

”Try Now” Button

1. Opens demo page in new tab
2. URL: /demo?agentId={agentId}&agentName={name}
3. Pre-selects the agent
4. Ready to start test call

• Select from/to phone numbers
• Start call button
• Real-time transcription
• Call duration timer
• End call button

​

Testing Best Practices

​

Pausing/Activating an Agent

​

Pause an Agent

1. Click Pause button on agent card
2. Agent status changes to “paused”
3. Agent cannot receive new calls
4. Existing calls complete normally

• Outside business hours
• Agent needs configuration updates
• Temporary suspension

​

Activate an Agent

1. Click Try Now to test first (recommended)
2. Or go to agent edit page
3. Agent status changes to “active”
4. Agent can receive calls immediately

​

Editing an Agent

​

Access Edit Page

1. Click Edit button on agent card
2. Opens configuration page
3. URL: /agents/create-agent/{agentId}

• Navigate to: /agents/create-agent/{agentId}
• Replace {agentId} with actual agent ID

​

Editable Settings

• Name & Description
• System Prompt
• Architecture (cannot change after creation)
• LLM Model
• STT Provider
• TTS Voice
• Temperature
• Inactivity Timeout
• Greeting Configuration
• Functions (Built-in & Custom)
• Languages
• Visibility Mode (Public/Private/Commercial)

​

Saving Changes

• Required fields checked
• Architecture-specific validation
• API key validation (if using My Keys mode)

• Toast notification: “Agent updated successfully!”
• Redirects back to agents list
• Agent card updates with new info

​

Deleting an Agent

​

Delete from Card

1. Click trash icon
2. Confirmation dialog appears:
   • “Are you sure you want to delete this agent?”
   • “This action cannot be undone.”
3. Click Confirm or Cancel

​

What Gets Deleted

• Agent configuration
• Agent languages
• Associated subagents
• Custom functions (if only used by this agent)

• Call logs (historical data)
• Transcripts
• Recordings
• Analytics data
• Billing records

​

After Deletion

• Agent card removed from list
• Agent cannot receive new calls
• Active calls complete normally
• API returns 404 for agent ID

• If on edit page → redirects to agents list
• If on demo page → shows error

​

Agent Status Indicators

​

Status Badge

​

Status in List

• Shows in header
• Counts only active agents
• Updates in real-time

• Active → Shows “Pause” button
• Paused → Shows “Try Now” button

​

Filtering & Search

​

Current Implementation

• Use browser search (Ctrl+F) to find agent by name
• Scroll through cards (grid layout)
• Agents ordered by creation date (newest first)

​

Future Features (Planned)

• Filter by architecture (Pipeline/Realtime/Text)
• Filter by status (Active/Paused)
• Filter by visibility (Public/Private/Commercial)
• Filter by date range

• Search by agent name
• Search by description
• Search by system prompt content

​

Empty State

​

When No Agents Exist

1. Icon: Large bot icon (purple gradient circle)
2. Heading: “No agents in ”
3. Subtext: “Create your first voice AI agent for this organization”
4. Action Button: “Create Agent” with dropdown

• Click “Create Agent”
• Select agent type from dropdown
• Redirects to configuration page

​

When No Organization Selected

• Icon: Alert triangle
• Heading: “No Organization Selected”
• Message: “Please select an organization from the sidebar to view agents”

1. Go to sidebar
2. Click organization selector
3. Select an organization
4. Agents list refreshes automatically

​

Loading States

​

Skeleton Loading

• Gray placeholder cards
• Animated pulse effect
• Shows card structure:
  • Icon placeholder
  • Title placeholder
  • Description placeholder
  • Stats placeholders
  • Button placeholders

• Typically 500-1000ms
• Retries up to 3 times on failure

​

Error State

• Toast notification: “Failed to load agents. Please refresh the page.”

• Click refresh button in browser
• Or press F5
• Re-fetches agents

​

Keyboard Shortcuts

• N — New agent
• Ctrl+F — Search agents (browser native)
• Enter — Open selected agent
• Delete — Delete selected agent (with confirmation)

​

Mobile Responsiveness

​

Layout Adaptations

• 3-column grid
• Full card details visible
• Side-by-side buttons

• 2-column grid
• Compressed card details
• Stacked buttons

• 1-column grid
• Simplified card layout
• Full-width buttons
• Collapsible details

​

Touch Interactions

• Larger tap targets (44px minimum)
• Swipe gestures (future)
• Pull-to-refresh (future)
• Bottom sheet for actions (future)

​

Real-Time Updates

​

Auto-Refresh

• Manual refresh required
• Click browser refresh button
• Or press F5

• Auto-refresh every 30 seconds
• WebSocket for real-time updates
• Toast notifications for changes

​

Cross-Tab Sync

• Uses CustomEvent for cross-tab communication
• Event name: agentUpdated

• created — New agent created
• updated — Agent configuration changed
• deleted — Agent removed

• If agent updated in one tab
• Other tabs receive event
• Agents list refreshes automatically
• No manual refresh needed

​

Agent Statistics

​

Displayed Stats

• Architecture type
• LLM model
• Voice (if applicable)
• Status (Active/Paused)

• Total active agents count
• Real-time counter

​

Future Stats (Planned)

• Calls today
• Total calls
• Success rate
• Average duration
• Last used timestamp

• Total calls across all agents
• Total minutes used
• Success rate average
• Top performing agents

​

Troubleshooting

​

Related Documentation

• Create an Agent — Step-by-step agent creation guide
• Agent Architectures — Pipeline vs Realtime vs Text
• Testing Agents — How to test your agents
• Subagents — Create multi-agent hierarchies
• API Reference — Programmatic agent management

​

API Endpoints

​

List Agents

GET /api/agents?organizationId={orgId}
Authorization: Bearer YOUR_SESSION_TOKEN

{
  "agents": [
    {
      "id": "agent_abc123",
      "name": "Customer Support Bot",
      "description": "Handles customer inquiries",
      "agentArchitecture": "pipeline",
      "model": "gpt_4o_mini",
      "stt": "deepgram",
      "voiceId": "cartesia-voice-123",
      "realtimeProvider": null,
      "status": "active",
      "callsToday": 15,
      "successRate": 0.95
    }
  ]
}

​

Create Agent

POST /api/agents
Content-Type: application/json

{
  "name": "New Agent",
  "description": "My new agent",
  "languages": ["english"],
  "agentArchitecture": "pipeline",
  "model": "gpt_4o_mini",
  "stt": "deepgram",
  "voiceId": "cartesia-voice-123",
  "sysMsg": "You are a helpful assistant",
  "organizationId": "org_123"
}

​

Delete Agent

DELETE /api/agents/{agentId}
Authorization: Bearer YOUR_SESSION_TOKEN