Build your first AI voice agent — 10-minute tutorial

pip install kataven   # or: npm install @kataven/server
export KATAVEN_API_KEY="sk_live_acme_..."
# KATAVEN_ACCOUNT_ID is NOT required for sk_live_ keys —
# the account is in the prefix.

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"])

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

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

result = client.calls.originate(
    from_number="+12025550123",
    to_number="+14155550100",   # 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']}")

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"])

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