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

# Playbooks & FAQs

> Reusable knowledge bundles attached to agents.

Two complementary primitives for giving agents context without
ballooning the system prompt.

## Playbooks

A playbook is a **prompt fragment + a list of tool names**. Think of
it as a self-contained capability: "I know how to book appointments,
and to do that I need these three tools available."

```json theme={null}
{
  "id": "uuid",
  "name": "appointments",
  "display_name": "Appointment booking",
  "category": "scheduling",
  "description": "Books, reschedules, and cancels appointments.",
  "tool_names": ["check_availability", "book_appointment", "cancel_appointment"],
  "tags": ["calendar"]
}
```

When an agent has a playbook attached, the playbook's prompt body
gets merged into the agent's system prompt at runtime, and the agent
becomes aware of the listed tools.

### Why bundle tools and prompt?

Because the prompt and the tool list have to agree. A "book an
appointment" prompt is useless if the `book_appointment` tool isn't
available. Wrapping them together as a playbook prevents the
"prompt mentions a tool that doesn't exist" bug and makes capabilities
composable.

### Built-in vs custom

Same model as tools: `is_default = true` for shipped playbooks,
custom ones can be created, updated, and deleted.

## FAQs

A FAQ is one **question + answer + category**. Surfaced to the agent
as quick-lookup knowledge for common questions.

```json theme={null}
{
  "id": "uuid",
  "name": "shipping-times",
  "category": "logistics",
  "title": "How long does shipping take?",
  "summary": "2–5 business days domestic.",
  "content": "Standard shipping arrives within 2–5 business days...",
  "tags": ["shipping", "logistics"]
}
```

FAQs are simpler than playbooks — no tool dependencies, no prompt
fragment. Just attached knowledge.

## Operations

| Operation             | Playbooks                                  | FAQs                                   |
| --------------------- | ------------------------------------------ | -------------------------------------- |
| List                  | `GET /api/playbooks`                       | `GET /api/faqs`                        |
| Get (by UUID or name) | `GET /api/playbooks/{id}`                  | `GET /api/faqs/{id}`                   |
| Create                | `POST /api/playbooks`                      | `POST /api/faqs`                       |
| Update                | `PUT /api/playbooks/{id}`                  | `PUT /api/faqs/{id}`                   |
| Delete custom         | `DELETE /api/playbooks/{id}`               | `DELETE /api/faqs/{id}`                |
| Attach to agent       | `POST /api/agents/{id}/playbooks`          | `POST /api/agents/{id}/faqs`           |
| Detach from agent     | `DELETE /api/agents/{id}/playbooks/{pbId}` | `DELETE /api/agents/{id}/faqs/{faqId}` |

## When to use which

| If you want…                                            | Use                                      |
| ------------------------------------------------------- | ---------------------------------------- |
| Reusable capability across many agents (with its tools) | **Playbook**                             |
| Static Q\&A entries the agent can quote                 | **FAQ**                                  |
| Per-agent config that no one else will touch            | Inline it in the agent's `system_prompt` |