Skip to main content

​
Agent Basics

Learn the fundamentals of managing AI agents in BlackBox, including lifecycle states, creation workflows, organization strategies, and health monitoring.

​
Agent Lifecycle

Every agent in BlackBox has an enabled/disabled toggle that controls its availability and behavior. Understanding this toggle is essential for effective agent management.

​
Enabled State

When you create an agent or toggle it to Enabled, it becomes active:
  • Characteristics:
    • Agent is fully active and can handle calls
    • Configuration changes take effect immediately
    • Appears in call routing and web integrations
    • Billable when processing calls
    • Can receive inbound calls if phone numbers are configured
    • Can be used for outbound call campaigns
  • Use Cases:
    • Production agents handling real customer interactions
    • Active support bots on your website
    • Outbound sales or reminder campaigns
    • Any scenario requiring immediate availability
Important: Configuration changes to enabled agents take effect immediately and can impact active calls. Consider disabling the agent first if you want to test changes without impacting live calls.

​
Disabled State

When you toggle an agent to Disabled, it becomes temporarily inactive:
  • Characteristics:
    • Agent stops accepting new calls
    • Active calls in progress complete normally
    • Configuration is preserved exactly as-is
    • No billing for disabled time
    • Can be re-enabled at any time
    • Historical call data remains accessible
  • Use Cases:
    • Temporary service maintenance or updates
    • Seasonal agents (e.g., holiday support bots)
    • A/B testing alternate configurations
    • Emergency pause during issues
Lifecycle Summary: Agents can be toggled between Enabled and Disabled states as many times as needed without losing configuration or historical data. New agents are enabled by default on creation.

​
Creating Agents

BlackBox provides two primary methods for creating agents: the web dashboard for visual configuration and the REST API for programmatic control.

​
Via Dashboard

The dashboard provides a guided, multi-tab interface for comprehensive agent configuration. Step-by-Step Process:
  1. Navigate to Agents Page
  2. Click “Create Agent” Button
    • Located in the top-right corner of the Agents page
    • Opens the multi-tab agent creation form
  3. Configure Basic Info Tab
    • Name: Descriptive identifier (e.g., “Customer Support - NA Region”)
    • System Prompt: Define personality and behavior
    • Primary Language: Select from 40 supported languages
  4. Configure LLM Tab
    • Choose vendor: openai, groq, grok, deepseek, customCompatible
    • Select model (e.g., gpt-4.1-mini, llama-3.3-70b-versatile)
    • Adjust temperature, maxTokens, topP as needed
  5. Configure Voice & Speech Tab
    • Choose TTS provider: ElevenLabs, Cartesia, Dasha, Inworld
    • Select a voice and preview it
    • Adjust speed (if supported by provider)
  6. Configure Optional Tabs (as needed)
    • Tools: Define custom functions
    • MCP Connections: Connect external tool servers
    • Phone & SIP: Configure telephony settings
    • Schedule: Set business hours
    • Features: Enable runtime capabilities
    • Webhooks: Configure event notifications
  7. Review and Save
    • Navigate to Review tab
    • Verify all settings
    • Click “Save Agent”
  8. Enable Agent (when ready)
    • Toggle “Allow this agent to take calls” switch
    • Agent becomes active immediately
For detailed guidance, see Creating Your First Agent.

​
Via API

The REST API provides programmatic control for creating agents in automated workflows. Basic Example (JavaScript): 
const response = await fetch('https://blackbox.dasha.ai/api/v1/agents', {
  method: 'POST',
  headers: {
    'Authorization': 'Bearer YOUR_API_KEY',
    'Content-Type': 'application/json'
  },
  body: JSON.stringify({
    name: "Customer Support Agent",
    description: "Handles customer inquiries and support tickets",
    isEnabled: true, // Enable on creation
    config: {
      version: "v1",
      primaryLanguage: "en-US",
      llmConfig: {
        version: "v1",
        vendor: "openai",
        model: "gpt-4.1-mini",
        prompt: "You are a helpful customer support agent. Be concise and friendly.",
        options: {
          temperature: 0.7,
          maxTokens: 2000
        }
      },
      ttsConfig: {
        version: "v1",
        vendor: "Dasha",
        voiceId: "default-voice",
        model: "common",
        speed: 1.0
      },
      sttConfig: {
        version: "v1",
        vendor: "Auto"
      },
      features: {
        version: "v1",
        languageSwitching: {
          version: "v1",
          isEnabled: true
        },
        rag: {
          version: "v1",
          isEnabled: false,
          kbLinks: []
        }
      }
    }
  })
});

const agent = await response.json();
console.log(`Created agent: ${agent.agentId}`);
Advanced Example with Tools and Webhooks: 
const response = await fetch('https://blackbox.dasha.ai/api/v1/agents', {
  method: 'POST',
  headers: {
    'Authorization': 'Bearer YOUR_API_KEY',
    'Content-Type': 'application/json'
  },
  body: JSON.stringify({
    name: "Sales Qualification Bot",
    isEnabled: true, // Enable immediately
    config: {
      version: "v1",
      primaryLanguage: "en-US",
      llmConfig: {
        version: "v1",
        vendor: "openai",
        model: "gpt-4.1",
        prompt: "You are a sales qualification specialist. Ask questions to understand the prospect's needs, budget, and timeline.",
        options: {
          temperature: 0.8,
          maxTokens: 2500
        }
      },
      ttsConfig: {
        version: "v1",
        vendor: "ElevenLabs",
        voiceId: "21m00Tcm4TlvDq8ikWAM", // Rachel voice
        model: "eleven_turbo_v2_5",
        speed: 1.0
      },
      sttConfig: {
        version: "v1",
        vendor: "Auto"
      },
      tools: [
        {
          name: "check_availability",
          description: "Check calendar availability for demos",
          schema: {
            type: "object",
            properties: {
              date: { type: "string", description: "Requested date (YYYY-MM-DD)" },
              time: { type: "string", description: "Requested time (HH:MM)" }
            },
            required: ["date", "time"]
          },
          webhook: {
            url: "https://api.example.com/webhooks/check-availability"
          }
        }
      ],
      resultWebhook: {
        url: "https://api.example.com/webhooks/call-completed"
      },
      features: {
        version: "v1",
        languageSwitching: {
          version: "v1",
          isEnabled: true
        },
        rag: {
          version: "v1",
          isEnabled: false,
          kbLinks: []
        }
      }
    },
    schedule: {
      timezone: "America/New_York",
      mon: [{ start: { hour: 9, minute: 0 }, end: { hour: 17, minute: 0 } }],
      tue: [{ start: { hour: 9, minute: 0 }, end: { hour: 17, minute: 0 } }],
      wed: [{ start: { hour: 9, minute: 0 }, end: { hour: 17, minute: 0 } }],
      thu: [{ start: { hour: 9, minute: 0 }, end: { hour: 17, minute: 0 } }],
      fri: [{ start: { hour: 9, minute: 0 }, end: { hour: 17, minute: 0 } }]
    }
  })
});

const agent = await response.json();
console.log(`Created and enabled agent: ${agent.agentId}`);
API Best Practice: Create agents with isEnabled: true (the default), but disable (isEnabled: false) during initial testing if you want to prevent accidental call handling. Re-enable via PUT /api/v1/agents/{agentId} when ready for production.

​
Managing Agents

BlackBox provides comprehensive agent management capabilities through both the dashboard and API.

​
Listing Agents

Via Dashboard:
  • Navigate to the Agents page to see all agents
  • View agent cards showing: Name, status badge (Enabled/Disabled), system prompt summary, feature counts
  • Use search bar to find specific agents by name
  • Filter by status using the dropdown (All/Enabled/Disabled)
  • Toggle between grid and list views
Via API: 
const response = await fetch('https://blackbox.dasha.ai/api/v1/agents', {
  method: 'GET',
  headers: {
    'Authorization': 'Bearer YOUR_API_KEY'
  }
});

const agents = await response.json();
console.log(`You have ${agents.length} agents`);

// Filter enabled agents
const enabledAgents = agents.filter(a => a.isEnabled);
console.log(`${enabledAgents.length} agents are currently enabled`);

​
Viewing Agent Details

Via API: 
const response = await fetch(
  `https://blackbox.dasha.ai/api/v1/agents/${agentId}`,
  {
    method: 'GET',
    headers: {
      'Authorization': 'Bearer YOUR_API_KEY'
    }
  }
);

const agent = await response.json();
console.log('Agent Details:', {
  name: agent.name,
  isEnabled: agent.isEnabled,
  language: agent.config.primaryLanguage,
  llmVendor: agent.config.llmConfig.vendor,
  llmModel: agent.config.llmConfig.model,
  ttsVendor: agent.config.ttsConfig.vendor,
  ttsVoiceId: agent.config.ttsConfig.voiceId,
  createdTime: agent.createdTime,
  lastUpdateTime: agent.lastUpdateTime
});

​
Editing Agents

Via Dashboard:
  • Click on an agent card from the Agents page
  • Click “Edit” button
  • Modify any configuration in the multi-tab form
  • Click “Save Agent” to apply changes
Live Agent Updates: Changes to enabled agents take effect immediately. Disable the agent first if you want to test changes without impacting live calls.
Via API: 
// Update agent configuration
const response = await fetch(
  `https://blackbox.dasha.ai/api/v1/agents/${agentId}`,
  {
    method: 'PUT',
    headers: {
      'Authorization': 'Bearer YOUR_API_KEY',
      'Content-Type': 'application/json'
    },
    body: JSON.stringify({
      name: "Customer Support Agent - Updated",
      isEnabled: true,
      config: {
        version: "v1",
        primaryLanguage: "en-US",
        llmConfig: {
          version: "v1",
          vendor: "openai",
          model: "gpt-4.1", // Upgraded model
          prompt: "You are a customer support expert. Be helpful and patient.",
          options: {
            temperature: 0.6 // Lower for more consistent responses
          }
        },
        ttsConfig: {
          version: "v1",
          vendor: "ElevenLabs",
          voiceId: "21m00Tcm4TlvDq8ikWAM",
          model: "eleven_turbo_v2_5"
        },
        sttConfig: {
          version: "v1",
          vendor: "Auto"
        },
        features: {
          version: "v1",
          languageSwitching: {
            version: "v1",
            isEnabled: true
          },
          rag: {
            version: "v1",
            isEnabled: false,
            kbLinks: []
          }
        }
      }
    })
  }
);

const updatedAgent = await response.json();
console.log('Agent updated:', updatedAgent.agentId);

​
Deleting Agents

Via Dashboard:
  • Click on an agent card from the Agents page
  • Click the three-dot menu on the agent card
  • Click “Delete” option
  • Confirm deletion in the confirmation dialog
Via API: 
const response = await fetch(
  `https://blackbox.dasha.ai/api/v1/agents/${agentId}`,
  {
    method: 'DELETE',
    headers: {
      'Authorization': 'Bearer YOUR_API_KEY'
    }
  }
);

if (response.ok) {
  console.log('Agent deleted successfully');
}
Permanent Deletion: Deleting an agent removes its configuration permanently and cannot be undone. Historical call data is preserved but the agent cannot be restored.

​
Agent Organization

Effective agent organization is critical when managing multiple agents across different use cases, regions, or campaigns.

​
Naming Conventions

Clear, consistent naming helps teams quickly identify and manage agents. Recommended Patterns:
  • Support - General Inquiries
  • Support - Technical Issues
  • Sales - Lead Qualification
  • Sales - Demo Scheduling
  • Billing - Payment Support
Best Practices:
  • Use descriptive prefixes for grouping (e.g., “Support -”, “Sales -”)
  • Include language/region when managing multilingual agents
  • Add campaign or version identifiers for A/B testing
  • Avoid generic names like “Agent 1”, “Test”, “Bot”
  • Keep names concise but meaningful (under 50 characters)

​
Managing Multiple Agents

When operating at scale, consider these strategies: Organizational Strategies:
  1. Functional Separation: Different agents for support, sales, billing
  2. Regional Deployment: Agents optimized for specific regions/languages
  3. Load Distribution: Multiple identical agents to handle high call volumes
  4. A/B Testing: Parallel agents with different configurations
  5. Specialized Experts: Agents trained for specific product lines or services
Tracking and Metadata: Use the additionalData field to store custom metadata: 
{
  name: "Support - General - NA",
  additionalData: {
    department: "customer-support",
    region: "north-america",
    version: "v2.1",
    campaignId: "spring-2025",
    owner: "support-team@example.com",
    costCenter: "CC-1001"
  }
}
This metadata helps with:
  • Filtering and searching agents
  • Cost allocation and reporting
  • Team ownership assignment
  • Campaign performance tracking

​
Monitoring Agent Health

Continuous monitoring ensures agents perform optimally and meet business objectives.

​
Key Metrics

Call Volume Metrics:
  • Calls Handled: Total calls processed (today, week, month)
  • Success Rate: Percentage of completed vs failed calls
  • Average Call Duration: Mean conversation length
  • Queue Depth: Current number of calls waiting
Performance Metrics:
  • Response Latency: Time from user speech to agent response
  • Completion Rate: Percentage of conversations reaching intended outcome
  • Error Rate: Failed calls, timeouts, or system errors
  • User Satisfaction: Post-call survey ratings (if configured)
Via API - Get Call Statistics: 
const response = await fetch(
  'https://blackbox.dasha.ai/api/v1/calls/statistics/statuses',
  {
    method: 'GET',
    headers: {
      'Authorization': 'Bearer YOUR_API_KEY'
    }
  }
);

const data = await response.json();
console.log('Call Statistics:', data.statuses);
// Output: { Queued: 5, Running: 2, Completed: 145, Failed: 3, Canceled: 1 }

​
Performance Indicators

Positive Indicators:
  • High completion rate (above 90%)
  • Low error rate (under 5%)
  • Consistent response latency (under 2 seconds)
  • High user satisfaction (above 4/5 stars)
  • Steady call volume without queue buildup
Warning Signs:
  • Increasing error rates
  • Rising average call duration (may indicate confusion)
  • Low completion rates (users hanging up early)
  • Queue depth growing faster than processing
  • Inconsistent response times

​
Health Monitoring Best Practices

  1. Set Baselines: Establish normal performance ranges for your agents
  2. Monitor Trends: Watch for gradual degradation over time
  3. Alert on Anomalies: Configure alerts for sudden metric changes
  4. Review Transcripts: Regularly sample conversations for quality
  5. Iterate Configuration: Continuously refine prompts and settings
Example Monitoring Workflow: 
// Daily health check script
async function checkAgentHealth(agentId) {
  // Get agent details
  const agent = await fetch(
    `https://blackbox.dasha.ai/api/v1/agents/${agentId}`,
    { headers: { 'Authorization': `Bearer ${API_KEY}` } }
  ).then(r => r.json());

  // Get recent calls
  const data = await fetch(
    `https://blackbox.dasha.ai/api/v1/calls/list?agentId=${agentId}`,
    { headers: { 'Authorization': `Bearer ${API_KEY}` } }
  ).then(r => r.json());

  // Calculate metrics
  const calls = data.calls;
  const total = calls.length;
  const completed = calls.filter(c => c.status === 'Completed').length;
  const failed = calls.filter(c => c.status === 'Failed').length;
  const successRate = (completed / total * 100).toFixed(2);

  console.log(`Agent: ${agent.name}`);
  console.log(`Success Rate: ${successRate}%`);
  console.log(`Total Calls: ${total}, Completed: ${completed}, Failed: ${failed}`);

  if (successRate < 85) {
    console.warn('⚠️ Success rate below threshold! Review agent configuration.');
  }
}

​
Next Steps

Now that you understand agent basics:

​
API Cross-Refs