What makes up an agent

The agent

An agent is the thing that actually handles a conversation. It bundles instructions (a system prompt plus a greeting), a persona (voice, language, and tone), a model, knowledge bases, and a set of tools — and it can talk over voice calls, web calls, and chat. The same agent record can serve PSTN and WebRTC at the same time.

{
  "id": "agt_abc123",
  "name": "Bookings Concierge",
  "description": "Books appointments at Acme Clinic.",
  "personaId": "p47e2c12-8b8d-4f8e-9b16-7c1a8f9c3a01",
  "status": "active",
  "model": null,
  "createdAt": "2026-05-09T12:00:00.000Z",
  "updatedAt": "2026-05-09T12:00:00.000Z"
}

The agent record on the API surface is intentionally lean — name, description, personaId, status, timestamps. The full runtime config (per-agent LLM, tools, knowledge, instructions) lives in related resources and is resolved by the agent runtime when a call starts.

Personas

A persona is a reusable bundle of voice, language, accent, and tone. Define it once ("warm Gulf Arabic receptionist") and reuse it across agents that differ only in tools or knowledge. Personas are managed in the dashboard under Studio → Voice Lab.

Knowledge

Knowledge bases are uploaded documents the agent can search mid-conversation — files, URLs, and raw text all work. Attach them via knowledgeBaseIds on the agent record and Qalyb auto-generates the right tool bindings for you.

Voices

The voice lives on the persona, not directly on the agent. Pick one from the catalog — or use a cloned voice — when you build the persona, and the agent inherits it. Swap the voice any time by updating the persona; no redeploy needed.

Tools

Tools are typed function calls the agent can invoke during a conversation. Each tool is a JSON schema plus a callback URL Qalyb hits when the agent decides to use it. Common patterns:

• book_appointment — write to your scheduling system.
• lookup_customer — read from your CRM.
• transfer_to_human — escalate to a live agent.

Channels

An agent runs on multiple channels by default — outbound and inbound voice (PSTN), web calls (WebRTC), and chat (HTTP + widget). Channel-specific behavior is controlled by which endpoint you hit: POST /v1/agents/{id}/calls for PSTN, POST /v1/agents/{id}/web-call for WebRTC.

Variables

Pass per-call context with the optional variables object on every call request. Reference variables in your system prompt with {{variable_name}} placeholders to personalize without forking the agent.

For the platform-wide picture — channels, campaigns, credits, and how they all connect — see How Qalyb works.