Your first agent

Build, configure, and call an agent end-to-end in 10 minutes.

We’ll build a simple receptionist agent, attach it to a phone number, and place a test call.

Prerequisites

• A Kataven account with the dashboard accessible.
• Bearer token + account slug (see Authentication).
• Python 3.10+ or Node 20+.
• Provider account (Twilio / Plivo / Vobiz) and at least one phone number purchased on that provider.

pip install kataven   # or: npm install @kataven/server
export KATAVEN_API_KEY="eyJhbGciOi..."
export KATAVEN_ACCOUNT_ID="acme"

1. Create the agent

from kataven import KatavenClient
client = KatavenClient()

agent = client.agents.create(
    name="Front Desk",
    description="Greets callers and routes them.",
    status="active",
    system_prompt=(
        "You are the front desk for Acme Co. "
        "Greet callers warmly. If they ask about pricing, refer them to "
        "https://acme.com/pricing. If they need to book, use the "
        "book_appointment tool."
    ),
    greeting_message="Acme Co., how can I help you today?",
    llm_model="gpt-4o",
    voice_provider="cartesia",
    voice_id="a0e99841-438c-4a64-b679-ae501e7d6091",
)
print("Agent:", agent["id"])

2. Connect the carrier

Store your provider credentials (encrypted at rest):

provider = client.telephony.create_provider(
    provider="twilio",
    label="Production Twilio",
    credentials={
        "account_sid": "ACxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx",
        "auth_token": "your_auth_token",
    },
)

3. Register the phone number

number = client.telephony.create_number(
    e164="[phone]",
    provider="twilio",
    credentials_id=provider["id"],
    agent_id=agent["id"],
    inbound_enabled=True,
    outbound_enabled=True,
)

The number is now pinned to your agent — inbound calls will route here.

4. Place a test outbound call

result = client.calls.originate(
    from_number="[phone]",
    to_number="[phone]",   # your own cell, for testing
    agent_id=agent["id"],
)
print("Call dispatched:", result["provider_call_id"])
print("Watch live at:", f"https://hub.kataven.ai/conversations/{result['session_id']}")

5. Add knowledge

Attach a playbook of FAQs so the agent can answer common questions:

faq = client.faqs.create(
    name="hours",
    category="general",
    title="What are your business hours?",
    content="Mon–Fri 9am–6pm Pacific. Closed on US federal holidays.",
)
client.agents.attach_faq(agent["id"], faq["id"])

6. Watch a campaign run

If you have a CSV of leads:

with open("leads.csv", "rb") as f:
    campaign = client.campaigns.create(
        name="Cold outreach week 1",
        agent_id=agent["id"],
        phone_number_id=number["id"],
        contacts=f,
        max_concurrent_calls=3,
    )
client.campaigns.start(campaign["id"])

for event in client.campaigns.stream_events(campaign["id"]):
    metrics = event.get("metrics", {})
    print(f"connected={metrics.get('connected')} "
          f"completed={metrics.get('completed')} "
          f"failed={metrics.get('failed')}")

What’s next

• Outbound calls — cap planning, retries, error handling.
• Embed widget — same agent on your website.
• Manage with Claude — let Claude run all of this for you.