Agents

An agent is the core entity in Conversational AI. It defines what your AI says, how it sounds, what it knows, and how conversations are governed. Once an agent is created and its SIP UAC is configured, it registers to your telephony platform and begins handling calls.

Configuration

Every agent has a configuration object with five top-level sections:

asr — speech recognition

"asr": {
  "keywords": ["booking", "cancellation", "account number"]
}

keywords hints the speech recognition engine toward domain-specific terms that might otherwise be misheard.

turn — turn timing

"turn": {
  "timeout_seconds": 10,
  "silence_timeout_seconds": 3
}

timeout_seconds is the maximum time the agent waits for a caller to respond before moving on. silence_timeout_seconds is how long a pause in the caller's speech is treated as them finishing their turn.

tts — text to speech

"tts": {
  "voice_id": "a1b2c3d4-...",
  "settings": {
    "stability": 0.5,
    "similarity_boost": 0.75,
    "speed": 1.0
  }
}

voice_id is the ID of a voice from the voice catalogue. settings controls how the voice sounds: stability (0–1, lower is more expressive), similarity_boost (0–1, how closely the synthesised output matches the target voice), and speed (relative playback speed).

agent — language model behaviour

"agent": {
  "first_message": "Hello, thanks for calling. How can I help you today?",
  "language": "en",
  "prompt": {
    "text": "You are a helpful customer service agent for Acme Corp...",
    "temperature": 0.5,
    "model": "gpt-4o"
  },
  "knowledge_base": [
    { "type": "url", "id": "doc-uuid-...", "source": "https://..." }
  ],
  "tools": []
}

first_message is what the agent says when it answers the call. prompt.text is the system prompt that governs the agent's behaviour, tone, and scope. knowledge_base lists the knowledge base documents the agent can retrieve from — reference them by their ID.

conversation — limits

"conversation": {
  "max_duration_seconds": 600
}

max_duration_seconds is a hard ceiling on how long a single conversation can run.

analysis — data collection (optional)

"analysis": {
  "data_collection": {
    "customer_intent": {
      "type": "string",
      "description": "What the caller wanted to achieve"
    },
    "issue_resolved": {
      "type": "boolean",
      "description": "Whether the caller's issue was resolved"
    }
  }
}

When analysis.data_collection is defined, the agent extracts the named fields from the conversation and includes them in the conversation record and conversation.completed webhook payloads.

Agent generation

Rather than composing a configuration from scratch, you can use POST /agents/generate to create an agent automatically from a high-level description. Pass industry, use_case, and goal to receive a fully-formed agent with a prompt appropriate for that context.

GET /agents/generate-options returns the list of supported industry and use_case values.

Properties

Lifecycle

An agent is created with POST /agents and updated with PUT /agents/:id. Updates take effect on new calls — calls already in progress are not affected. An agent can be deleted with DELETE /agents/:id; this terminates any active SIP registration.