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

# Agents

> Voice & chat AI agents on Kataven — system prompt, voice, LLM model, attached tools and knowledge. The unit you configure, version, and pin to a phone number or widget.

An **agent** is a configured conversation runner. It holds a system
prompt, a voice, an LLM model, and a set of tools / playbooks / FAQs
it can draw on. End-users talk to agents — never directly to the
underlying model.

## What's on an agent

| Field                                                  | Notes                                                                          |
| ------------------------------------------------------ | ------------------------------------------------------------------------------ |
| `name`, `description`, `category`                      | Display only.                                                                  |
| `status`                                               | `draft` / `active` / `paused` / `archived`. Only `active` agents accept calls. |
| `system_prompt`                                        | The full instructional prompt fed to the LLM.                                  |
| `greeting_message`                                     | First thing the agent says.                                                    |
| `llm_model`                                            | `gpt-4o`, `claude-sonnet-4-6`, etc.                                            |
| `voice_provider` + `voice_id`                          | Cartesia / ElevenLabs / your provider here.                                    |
| `greeting_mode`                                        | `interruptible` (caller can talk over the greeting) or `locked`.               |
| `ringing_enabled`                                      | Whether to play a synthesized ring before pickup.                              |
| `background_audio_enabled` + `background_audio_volume` | Office-ambience track behind the agent's voice.                                |
| `noise_suppression_enabled`                            | DTLN inbound noise suppression.                                                |
| `auth_mode`                                            | `public` (anyone can talk) or `authenticated` (requires a signed widget JWT).  |
| `playbooks`, `faqs`                                    | Attached knowledge — see [Playbooks & FAQs](/concepts/playbooks-and-faqs).     |

## Lifecycle

```mermaid theme={null}
stateDiagram-v2
    [*] --> draft
    draft --> active: publish
    active --> paused: pause
    paused --> active: resume
    active --> archived: archive
    paused --> archived: archive
```

Only `active` agents accept inbound calls and originate outbound calls.

## Operations

| Operation       | Endpoint                                   | SDK                                                         |
| --------------- | ------------------------------------------ | ----------------------------------------------------------- |
| List            | `GET /api/agents`                          | `client.agents.list()`                                      |
| Get             | `GET /api/agents/{id}`                     | `client.agents.get(id)`                                     |
| Create          | `POST /api/agents`                         | `client.agents.create(...)`                                 |
| Update          | `PATCH /api/agents/{id}`                   | `client.agents.update(id, ...)`                             |
| Delete          | `DELETE /api/agents/{id}`                  | `client.agents.delete(id)`                                  |
| Attach playbook | `POST /api/agents/{id}/playbooks`          | `client.agents.attach_playbook(id, pb_id)`                  |
| Detach playbook | `DELETE /api/agents/{id}/playbooks/{pbId}` | `client.agents.detach_playbook(id, pb_id)`                  |
| Attach FAQ      | `POST /api/agents/{id}/faqs`               | `client.agents.attach_faq(id, faq_id)`                      |
| Configure tool  | `POST /api/agents/{id}/tools`              | `client.agents.upsert_tool(id, tool_name, config, enabled)` |

## Where agents talk

An agent is just config. The actual conversation runs in the
**Call Processor** (Pipecat-based, GPU-friendly). You connect the
agent to one of three transports:

1. **PSTN (phone)** — assign a `phone_number` to the agent
   (see [Telephony](/concepts/telephony)). Inbound rings the agent;
   outbound goes through `POST /api/v1/calls/originate`.
2. **WebRTC widget** — embed the JS SDK on a customer page
   (see [Widget](/concepts/widget)).
3. **Direct WebSocket** — for custom clients that speak the gateway
   protocol directly.