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

# Node SDK — agents

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

`AgentsResource` is reachable on every Kataven Node 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 Node. 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/{id}`                                | Get an agent                        |
| `create`         | `POST /api/agents`                                    | Create an agent                     |
| `update`         | `PATCH /api/agents/{id}`                              | Update an agent                     |
| `delete`         | `DELETE /api/agents/{id}`                             | Delete an agent                     |
| `listTools`      | `GET /api/agents/{agentId}/tools`                     | List tools attached to an agent     |
| `upsertTool`     | `POST /api/agents/{agentId}/tools`                    | Attach or update a tool on an agent |
| `attachPlaybook` | `POST /api/agents/{agentId}/playbooks`                | Attach a playbook to an agent       |
| `detachPlaybook` | `DELETE /api/agents/{agentId}/playbooks/{playbookId}` | Detach a playbook from an agent     |
| `attachFaq`      | `POST /api/agents/{agentId}/faqs`                     | Attach an FAQ to an agent           |
| `detachFaq`      | `DELETE /api/agents/{agentId}/faqs/{faqId}`           | 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)

```typescript theme={null}
list()
```

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)

```typescript theme={null}
get(id: string)
```

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)

```typescript theme={null}
create(input: AgentCreate)
```

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)

```typescript theme={null}
update(id: string, patch: Partial<AgentCreate>)
```

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

Delete an agent

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

```typescript theme={null}
delete(id: string)
```

### `client.agents.listTools(...)`

List tools attached to an agent

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

```typescript theme={null}
listTools(agentId: string)
```

### `client.agents.upsertTool(...)`

Attach or update a tool on an agent

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

```typescript theme={null}
upsertTool(agentId: string, toolName: string, config: Record<string, unknown> = {}, enabled = true)
```

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

### `client.agents.attachPlaybook(...)`

Attach a playbook to an agent

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

```typescript theme={null}
attachPlaybook(agentId: string, playbookId: string)
```

### `client.agents.detachPlaybook(...)`

Detach a playbook from an agent

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

```typescript theme={null}
detachPlaybook(agentId: string, playbookId: string)
```

### `client.agents.attachFaq(...)`

Attach an FAQ to an agent

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

```typescript theme={null}
attachFaq(agentId: string, faqId: string)
```

### `client.agents.detachFaq(...)`

Detach an FAQ from an agent

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

```typescript theme={null}
detachFaq(agentId: string, faqId: string)
```