> ## Documentation Index
> Fetch the complete documentation index at: https://docs.kataven.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# Build your first AI voice agent — 10-minute tutorial

> End-to-end walkthrough: create a Kataven voice agent, attach a Twilio/Plivo/Vobiz phone number, place a test call, attach an FAQ, run a campaign. Python SDK, ~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 dashboard access at [hub.kataven.ai](https://hub.kataven.ai).
* An `sk_live_` API key — mint one at [hub.kataven.ai/settings](https://hub.kataven.ai/settings) → **API Keys** tab → **Create API key**. See [Quickstart § 1](/quickstart#1-mint-an-api-key) for the full walkthrough.
* Python 3.10+ or Node 20+.
* Provider account (Twilio / Plivo / Vobiz) and at least one phone number purchased on that provider.

```bash theme={null}
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.
```

## 1. Create the agent

```python theme={null}
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):

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

## 3. Register the phone number

```python theme={null}
number = client.telephony.create_number(
    e164="+12025550123",
    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

```python theme={null}
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']}")
```

## 5. Add knowledge

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

```python theme={null}
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:

```python theme={null}
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')}")
```

## Verify in the dashboard

| What you built                             | Open in Hub UI                                                       |
| ------------------------------------------ | -------------------------------------------------------------------- |
| Agent (config + prompt + voice)            | [hub.kataven.ai/agents](https://hub.kataven.ai/agents)               |
| Phone number wired to agent                | [hub.kataven.ai/phone-numbers](https://hub.kataven.ai/phone-numbers) |
| The test call you placed (live transcript) | [hub.kataven.ai/conversations](https://hub.kataven.ai/conversations) |
| Campaign progress + per-contact status     | [hub.kataven.ai/campaigns](https://hub.kataven.ai/campaigns)         |
| FAQ entry attached                         | [hub.kataven.ai/knowledge](https://hub.kataven.ai/knowledge)         |

## What's next

<CardGroup cols={2}>
  <Card title="Outbound calls" icon="phone-arrow-up-right" href="/guides/outbound-call">
    Cap planning, retries, error handling for production outbound flows.
  </Card>

  <Card title="Embed the widget" icon="window" href="/guides/embed-widget">
    Put the same agent on your website with `pk_live_` widget keys.
  </Card>

  <Card title="Hand it off to AI" icon="sparkles" href="/guides/ai-agents">
    Let Claude Code, Claude Desktop, ChatGPT, or Codex run all of this for you.
  </Card>

  <Card title="API Reference" icon="terminal" href="/api-reference/introduction">
    Every endpoint with try-it. Generated from the same OpenAPI spec the SDKs are built on.
  </Card>
</CardGroup>