Build and call your first agent

About 5 minutesUpdated July 2026

An agent bundles a persona (voice, language, tone) with instructions and tools. Here you'll create one over the API, then have it dial a real phone number — two requests, start to finish.

Before you start, make sure you have:

A Qalyb account with dashboard access

A terminal with curl — or Node.js if you prefer the SDK

Tip:

prefer clicking to coding? Create your first agent builds an agent entirely from the dashboard — no code at all.

Get an API key

Mint a key in Settings → API Keys in the dashboard, then export it as QALYB_API_KEY so the snippets below can use it.

Pick (or build) a persona

Personas live in the dashboard under Voice Lab → Personas. Create one — pick a voice from the catalog, set a language, save — and note the persona id. It goes in as personaId below.

Create the agent

One request, with the instructions and greeting inline:

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."
    }
  }'

You get back an agent record with an id like agt_abc123 — keep it handy for the next step.

Place a call

Point the agent at a phone number and Qalyb dials it — your agent opens with its greeting and takes the conversation from there:

curl · bash

curl -X POST https://api.qalyb.ai/v1/agents/agt_abc123/calls \
  -H "Authorization: Bearer sk-live-..." \
  -H "Content-Type: application/json" \
  -d '{
    "phoneNumber": "+971501234567",
    "variables": {
      "customer_name": "Layla",
      "appointment_window": "Sunday afternoon"
    }
  }'

End-to-end with the SDK

The same two calls in TypeScript:

quickstart.ts · ts

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

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

// 1. Create the agent
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.',
  },
});

// 2. Place the outbound call
const call = await qalyb.agents.startCall(agent.id, {
  phoneNumber: '+971501234567',
  variables: { customer_name: 'Layla' },
});

console.log(call.id, call.status);

Next steps

Wire up webhooks to react when the call ends.
Embed web calls with WebRTC instead of PSTN.
Read what makes up an agent for the full picture.

Was this guide helpful?

← Previous

Authentication

What makes up an agent