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 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