Agents - Kataven

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.

Lifecycle

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:

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