Agents

Introduction

Agents are the core of the Chorus platform. An agent is an AI-powered conversational system that can handle phone calls autonomously, responding to customers in natural language and executing actions through custom tools.

What is an Agent?

An Agent is a configurable voice AI assistant that:

• Handles inbound and outbound phone calls
• Follows a system prompt to guide conversations
• Uses speech-to-text, language models, and text-to-speech for natural interactions
• Can call custom HTTP tools to fetch data or trigger actions
• Extracts structured data from conversations
• Sends webhooks with call summaries and results

Creating an Agent

Required Fields

Optional Fields

System Prompt

The system prompt is the most important configuration for your agent. It defines the agent's personality, goals, and conversation flow.

Best Practices

You are a friendly customer support agent for Acme Inc. Your goal is to help 
customers resolve their issues quickly and professionally.

Key Guidelines:
- Always greet the customer warmly
- Ask clarifying questions to understand their issue
- Be concise and avoid technical jargon
- If you can't help, offer to transfer to a human agent
- End calls politely and confirm if the issue was resolved

Important Context:
- Company hours: Monday-Friday, 9 AM - 5 PM EST
- Support email: support@acme.com
- Return policy: 30 days with receipt

Using Context Variables

You can use template variables in your system prompt that get replaced with call-specific data:

You are calling {{customer_name}} about their recent order #{{order_id}}.

Order Details:
- Product: {{product_name}}
- Order Date: {{order_date}}
- Shipping Status: {{shipping_status}}

Ask if they have any questions about their order.

When creating a call, pass these variables in the contextVariables field:

{
  "agentId": "agent-uuid",
  "phoneNumberId": "phone-uuid",
  "to": "+15551234567",
  "contextVariables": {
    "customer_name": "John Doe",
    "order_id": "12345",
    "product_name": "Premium Widget",
    "order_date": "2024-01-15",
    "shipping_status": "In Transit"
  }
}

Voice and Model Selection

Language Models

Choose from available language models optimized for real-time conversations. Different models offer various capabilities:

• Faster response times
• Better multilingual support
• Enhanced reasoning abilities
• Cost optimization

View available models using the /v1/slm-models endpoint.

Voices

Select from a variety of voices to match your brand and use case. Configure:

• Voice ID: The specific voice to use
• Voice Speed: Adjust speech rate (0.6x to 1.5x)

View available voices using the /v1/voices endpoint.

First Speaker and Greetings

First Speaker

Control who speaks first on the call:

• user (default): Agent waits for the person to speak first
• agent: Agent speaks immediately when the call connects

Agent Greeting

When firstSpeaker is set to "agent", you can configure the greeting:

• AI-Generated (agentGreetingEnabled: false): Agent generates a contextual greeting
• Custom Message (agentGreetingEnabled: true): Use your own greeting text

{
  "firstSpeaker": "agent",
  "agentGreeting": "Hi {{customer_name}}, this is calling from Acme Inc. Do you have a moment to talk about your recent inquiry?",
  "agentGreetingEnabled": true
}

Tools

Agents can be configured with custom HTTP tools that allow them to:

• Fetch customer data from your CRM
• Check inventory or order status
• Schedule appointments
• Create support tickets
• Trigger workflows

Learn more in the Tools documentation.

Post-Call Configuration

Call Summaries

Enable automatic call summarization:

{
  "postCallSummaryEnabled": true
}

Data Extraction

Extract structured data from conversations using a schema:

{
  "postCallExtractionSchema": [
    {
      "name": "customer_interest",
      "description": "What product or service is the customer interested in?",
      "type": "string"
    },
    {
      "name": "follow_up_needed",
      "description": "Does the customer need a follow-up call?",
      "type": "boolean"
    },
    {
      "name": "budget",
      "description": "What is the customer's budget range?",
      "type": "number"
    }
  ]
}

Webhooks

Receive POST requests when calls complete:

{
  "postCallWebhookUrl": "https://your-app.com/webhooks/call-completed",
  "postCallWebhookSecret": "your-webhook-secret"
}

The webhook payload includes:

• Call duration and status
• Transcript and recording URLs
• AI-generated summary
• Extracted data fields

Learn more in the Webhooks guide.

Agent Transfer

Agents can transfer calls to other agents during a conversation. Configure transfer targets to enable seamless handoffs between specialized agents.

For example:

• Transfer from a general support agent to a technical specialist
• Route sales calls to specific account managers
• Escalate to supervisors when needed

Advanced Turn-Taking Settings

Fine-tune how the agent detects when a user has finished speaking and manages interruptions:

These settings have sensible defaults and most agents won't need to change them. Adjust only if you need to fine-tune latency or turn-taking behavior.

Call Duration Limits

Set maximum call duration to manage costs and prevent excessive calls:

{
  "maxCallDurationSeconds": 1800  // 30 minutes
}

Calls automatically end when this limit is reached.

Example: Complete Agent Configuration

{
  "name": "Customer Support Agent",
  "systemPrompt": "You are a helpful support agent for Acme Inc...",
  "slmModelId": "model-uuid",
  "voiceId": "voice-uuid",
  "voiceSpeed": 1.0,
  "isActive": true,
  "allowEndCall": true,
  "firstSpeaker": "agent",
  "agentGreeting": "Hi, this is Alex from Acme support. How can I help you today?",
  "agentGreetingEnabled": true,
  "maxCallDurationSeconds": 600,
  "postCallSummaryEnabled": true,
  "postCallExtractionSchema": [
    {
      "name": "issue_resolved",
      "description": "Was the customer's issue resolved?",
      "type": "boolean"
    }
  ],
  "postCallWebhookUrl": "https://your-app.com/webhook"
}

Next Steps

• Learn about Phone Numbers to connect telephony
• Explore Tools to add capabilities to your agents
• Read the Calls documentation to start making calls

API Reference

• Create Agent
• List Agents
• Get Agent
• Update Agent
• Delete Agent