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

# Python SDK — agents

> Python SDK reference for Kataven agents — list, create, update, delete, attach playbooks/FAQs/tools.

`AgentsClient` is reachable on every Kataven client as `client.agents`. Each method maps to one HTTP endpoint on the [Hub API](/api-reference/introduction); links to the underlying spec entry are inline below.

Manage AI voice/chat agents from Python. Every method on `client.agents` maps to one HTTP endpoint on the [Hub API](/api-reference/introduction).

## Methods at a glance

| Method            | HTTP                                                    | Summary                             |
| ----------------- | ------------------------------------------------------- | ----------------------------------- |
| `list`            | `GET /api/agents`                                       | List agents                         |
| `get`             | `GET /api/agents/{agent_id}`                            | Get an agent                        |
| `create`          | `POST /api/agents`                                      | Create an agent                     |
| `update`          | `PATCH /api/agents/{agent_id}`                          | Update an agent                     |
| `delete`          | `DELETE /api/agents/{agent_id}`                         | Delete an agent                     |
| `list_tools`      | `GET /api/agents/{agent_id}/tools`                      | List tools attached to an agent     |
| `upsert_tool`     | `POST /api/agents/{agent_id}/tools`                     | Attach or update a tool on an agent |
| `attach_playbook` | `POST /api/agents/{agent_id}/playbooks`                 | Attach a playbook to an agent       |
| `detach_playbook` | `DELETE /api/agents/{agent_id}/playbooks/{playbook_id}` | Detach a playbook from an agent     |
| `attach_faq`      | `POST /api/agents/{agent_id}/faqs`                      | Attach an FAQ to an agent           |
| `detach_faq`      | `DELETE /api/agents/{agent_id}/faqs/{faq_id}`           | Detach an FAQ from an agent         |

## Reference

### `client.agents.list(...)`

List agents

**HTTP** — `GET /api/agents` · [API reference →](/api-reference/introduction#tag/Agents/operation/getApiAgents)

```python theme={null}
    def list(self) -> List[Dict[str, Any]]:
```

Returns every agent in the caller's account, with attached playbooks and FAQs joined in. Ordered by `created_at` descending. There is no pagination today — every account has at most a few dozen agents in practice; if that changes we'll add `limit`/`offset` like /api/tools and /api/playbooks.

### `client.agents.get(...)`

Get an agent

**HTTP** — `GET /api/agents/{id}` · [API reference →](/api-reference/introduction#tag/Agents/operation/getApiAgentsById)

```python theme={null}
    def get(self, agent_id: str) -> Dict[str, Any]:
```

Returns the agent row plus its attached playbooks and FAQs.

### `client.agents.create(...)`

Create an agent

**HTTP** — `POST /api/agents` · [API reference →](/api-reference/introduction#tag/Agents/operation/postApiAgents)

```python theme={null}
    def create(self, name: str, **kwargs) -> Dict[str, Any]:
```

Persists a new agent in the caller's account. Required body fields: `name`. Most other fields default sensibly: `category=custom`, `status=draft`, `llm_model=gpt-4o`, `voice_provider=cartesia`, `auth_mode=authenticated`, `greeting_mode=interruptible`. Returns the inserted row, including server-set `id`, `created_at`, and `updated_at`. Attach playbooks and FAQs separately via `POST /api/agents/{id}/playbooks` and `POST /api/agents/{id}/faqs`.

### `client.agents.update(...)`

Update an agent

**HTTP** — `PATCH /api/agents/{id}` · [API reference →](/api-reference/introduction#tag/Agents/operation/patchApiAgentsById)

```python theme={null}
    def update(self, agent_id: str, **kwargs) -> None:
```

### `client.agents.delete(...)`

Delete an agent

**HTTP** — `DELETE /api/agents/{id}` · [API reference →](/api-reference/introduction#tag/Agents/operation/deleteApiAgentsById)

```python theme={null}
    def delete(self, agent_id: str) -> None:
```

### `client.agents.list_tools(...)`

List tools attached to an agent

**HTTP** — `GET /api/agents/{id}/tools` · [API reference →](/api-reference/introduction#tag/Agents/operation/getApiAgentsByIdTools)

```python theme={null}
    def list_tools(self, agent_id: str) -> List[Dict[str, Any]]:
```

### `client.agents.upsert_tool(...)`

Attach or update a tool on an agent

**HTTP** — `POST /api/agents/{id}/tools` · [API reference →](/api-reference/introduction#tag/Agents/operation/postApiAgentsByIdTools)

```python theme={null}
    def upsert_tool(
        self,
        agent_id: str,
        tool_name: str,
        config: Optional[Dict[str, Any]] = None,
        enabled: bool = True,
    ) -> None:
```

Idempotent insert-or-update of one (agent\_id, tool\_name) row. Both POST and PUT are accepted.

### `client.agents.attach_playbook(...)`

Attach a playbook to an agent

**HTTP** — `POST /api/agents/{id}/playbooks` · [API reference →](/api-reference/introduction#tag/Agents/operation/postApiAgentsByIdPlaybooks)

```python theme={null}
    def attach_playbook(self, agent_id: str, playbook_id: str) -> Dict[str, Any]:
```

### `client.agents.detach_playbook(...)`

Detach a playbook from an agent

**HTTP** — `DELETE /api/agents/{id}/playbooks/{playbookId}` · [API reference →](/api-reference/introduction#tag/Agents/operation/deleteApiAgentsByIdPlaybooksByPlaybookId)

```python theme={null}
    def detach_playbook(self, agent_id: str, playbook_id: str) -> Dict[str, Any]:
```

### `client.agents.attach_faq(...)`

Attach an FAQ to an agent

**HTTP** — `POST /api/agents/{id}/faqs` · [API reference →](/api-reference/introduction#tag/Agents/operation/postApiAgentsByIdFaqs)

```python theme={null}
    def attach_faq(self, agent_id: str, faq_id: str) -> Dict[str, Any]:
```

### `client.agents.detach_faq(...)`

Detach an FAQ from an agent

**HTTP** — `DELETE /api/agents/{id}/faqs/{faqId}` · [API reference →](/api-reference/introduction#tag/Agents/operation/deleteApiAgentsByIdFaqsByFaqId)

```python theme={null}
    def detach_faq(self, agent_id: str, faq_id: str) -> Dict[str, Any]:
```