Create agents via API

About 10 minutesUpdated July 2026

After this page, you can run the full agent lifecycle from code: create an agent with a persona and instructions, then list, update, and delete it — no dashboard clicks required.

Before you start, make sure you have:

A live API key — see Authentication

A persona id — from a persona you built in the dashboard, or one of the system personas

Pick (or build) a persona

A persona bundles voice, language, and tone. Build one in the dashboard under Studio → Voice Lab → Personas, or reuse one of the system personas. The persona id is what you pass as personaId when creating an agent.

Screenshot: the Personas list showing a table of personas with Voice, Language, Style, Traits, and Preview columns — Each persona bundles a voice, language, and tone — copy its id to use as personaId.

Write the instructions

Pass an instructions object with a short systemPrompt (who the agent is, what it's allowed to do) and an optional greeting (the line the agent opens every conversation with). Use {{variable_name}} placeholders for anything you'll inject per-call.

Create the agent

curl · bash

curl -X POST https://api.qalyb.ai/v1/agents \
  -H "Authorization: Bearer sk-live-..." \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Bookings Concierge",
    "description": "Books appointments at Acme Clinic.",
    "personaId": "p47e2c12-8b8d-4f8e-9b16-7c1a8f9c3a01",
    "instructions": {
      "systemPrompt": "You are a friendly receptionist for Acme Clinic. Greet the caller, confirm the appointment time, and book it.",
      "greeting": "Marhaba! Welcome to Acme Clinic."
    },
    "knowledgeBaseIds": ["kb_clinic_faq"],
    "toolIds": ["book_appointment", "lookup_customer"]
  }'

From the SDK:

create-agent.ts · ts

import { Qalyb } from '@qalyb/sdk';

const qalyb = new Qalyb({ apiKey: process.env.QALYB_API_KEY! });

const agent = await qalyb.agents.create({
  name: 'Bookings Concierge',
  personaId: 'p47e2c12-8b8d-4f8e-9b16-7c1a8f9c3a01',
  description: 'Books appointments at Acme Clinic.',
  instructions: {
    systemPrompt:
      'You are a friendly receptionist for Acme Clinic. Greet the caller, confirm the appointment time, and book it.',
    greeting: 'Marhaba! Welcome to Acme Clinic.',
  },
  knowledgeBaseIds: ['kb_clinic_faq'],
  toolIds: ['book_appointment', 'lookup_customer'],
});

console.log(agent.id);

List your agents

curl · bash

curl https://api.qalyb.ai/v1/agents \
  -H "Authorization: Bearer sk-live-..."

Update fields any time

PATCH applies a partial update — only the fields you send change. Persona, instructions, knowledge bases, tools, status: all editable without redeploying.

curl · bash

curl -X PATCH https://api.qalyb.ai/v1/agents/agt_abc123 \
  -H "Authorization: Bearer sk-live-..." \
  -H "Content-Type: application/json" \
  -d '{
    "description": "Books appointments and renewals at Acme Clinic.",
    "instructions": { "systemPrompt": "Updated prompt..." },
    "status": "active"
  }'

Delete when you're done

curl · bash

curl -X DELETE https://api.qalyb.ai/v1/agents/agt_abc123 \
  -H "Authorization: Bearer sk-live-..."

Once the agent exists, put it to work: place a real phone call with Place calls via API, run it in the browser with web calls, or get notified about every conversation with webhooks.

Was this guide helpful?

← Previous

What makes up an agent

Place calls via API