> For the complete documentation index, see [llms.txt](https://help.sipgate.de/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://help.sipgate.de/ai-agents/en/behavior/playbooks.md).

# Playbooks

Playbooks define how your agent responds to specific requests and which steps are performed in the process. They are used when conversations should not only be answered, but handled in a targeted way, for example to collect information, check requests, or pass content on to your team.

Playbooks therefore form the basis for structured and automated conversation workflows.

### What are playbooks used for?

Playbooks are suitable for requests that require a clear, structured process:

* Record callback requests with full contact details
* Document support or service requests in a structured way
* Categorize and route invoice or contract questions
* Capture appointment requests when no calendar integration is connected

{% hint style="info" %}
**Calendar integration active?** Then do not create an additional playbook for scheduling appointments. Your agent automatically recognizes appointment requests and books them directly. An additional playbook can cause the request to be assigned incorrectly. More on this under Calendar.
{% endhint %}

A playbook consists of individual tasks. You define what the AI agent should do in the conversation:

* **Request information**, for example customer numbers, contact details, or problem descriptions
* **Pass on notes**, such as instructions or information for callers
* **Map simple if-then flows**, for example ask an additional question depending on an answer
* **Highlight important details in the summary**, so they are directly visible for follow-up work

Tasks can be created as mandatory or optional. This lets you tailor the conversation flow to the respective request.

More information can be found under [**Summaries & Transcripts**.](https://help.sipgate.de/ai-agents/en/post-processing/summaries-and-transcripts.md)

### Playbooks from the library

{% hint style="warning" icon="user-headset" %}
The playbook library is only available in **sipgate sona** If you do not see a library in your agent overview, continue directly with the section **“Own playbooks”** .
{% endhint %}

In the library you will find **prebuilt playbooks from sipgate** for common use cases, for example recording fault reports or retrieving orders. The library is continuously being expanded.

The playbooks are already preconfigured and **partly editable**:

* **Add your own details:** Fill in the provided fields with your information.
* **Connect tools:** Connect the required tools.
* **Triggers and flow:** These are fixed and cannot be changed.

You will find the library in the **sidebar of the agent overview**. Drag the desired playbook by **drag and drop onto your agent**.

**Don't see a suitable playbook?** Then create your own.

### Own playbooks

You create your own playbook **from scratch** and configure it completely yourself. You define how your agent handles a conversation:

* **Request information:** For example customer numbers, problem descriptions, or contact options.
* **Confirm details:** The agent confirms the collected information.
* **Pass on results:** For example by email, webhook, or as a summary in the sipgate app.

Newly created playbooks are **initially deactivated**. Only after activation will your agent use them for suitable requests. Deactivated playbooks are ignored and do not need to be deleted.

How many playbooks you can create depends on your plan:

* **sipgate sona Free:** Up to three playbooks.
* **All other plans:** An unlimited number of playbooks.

### **Name and describe playbook**

**Title and description** help your agent choose the right playbook. Make both specific and clearly distinguish the topics from each other. Test the selection with different requests and adjust the details if necessary.

### **Set conditions**

Define **keywords, phrases, or specific requests**, that should trigger the playbook. Regularly check whether the conditions are taking effect and adjust them if necessary.

### **Use tasks**

With tasks, you define what your agent should do in the conversation:

* **Request information**, for example customer numbers or contact details.
* **Ask follow-up questions**, when certain information is available. For this, use optional tasks.
* **Give notes and instructions.**

Mark important tasks so they are **conversation summary** highlighted there. More on this under [**Summaries & Transcripts**](https://help.sipgate.de/ai-agents/en/post-processing/summaries-and-transcripts.md).

### Reference MCP tools in tasks

In the instructions of a task, you can reference MCP tools. Type `@` in the instructions field — a selection menu with the available tools will appear.

Select the desired tool. It will appear under **Linked tools** in the task and will be used by your agent in the conversation.

{% hint style="warning" icon="user-headset" %}
Referencing MCP tools in tasks is not available for **sipgate sona Free** .
{% endhint %}

<img src="https://3225157888-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FL8XuEunVQH0eqk0OHmIg%2Fuploads%2FkYed90hJuE3bA0ExavZ1%2Funknown.png?alt=media&amp;token=7e28c669-d2ee-43cb-a2bc-6bc220cac936" alt="" height="497" width="602">

### **Connections**

As soon as a playbook references an MCP tool, you will see under **Connections** in the playbook overview which tools are connected and whether the connection is active.

**Connection interrupted:** If an MCP server is no longer reachable, sipgate automatically deactivates all active playbooks that use tools from this server. Re-establish the MCP connection and then manually activate the playbook via **Activate**.

### **Define completion action**

Choose a **forwarding to a phone number or a channel** or a **callback** as the completion action.

Channels do not require their own routed phone number. In the analytics dashboard you can see which channel the call was forwarded to.

Obtain the **consent of the callers** via a task and, if necessary, define alternatives, such as ending the conversation if no callback is desired.

### Interaction with knowledge and customer questions

**Playbooks control the flow.** The [**knowledge base**](https://help.sipgate.de/ai-agents/en/behavior/wissensdatenbank.md) and the [**customer questions**](https://help.sipgate.de/ai-agents/en/behavior/kundenfragen.md) provide the information for your agent's answers.


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation by asking a question.

Perform an HTTP GET request on the following URL with the `ask` and `goal` query parameters:

```
GET https://help.sipgate.de/ai-agents/en/behavior/playbooks.md?ask=<question>&goal=<user_goal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is what the user is ultimately trying to achieve, the reason they need the answer. Sharing it helps GitBook give you a better, more relevant answer. A goal is most helpful when it describes the outcome the user wants rather than restating the question. For example, with `ask=how do I create an API token`, a goal like `automate deployments from our CI pipeline` lets GitBook tailor the answer to that use case.

The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.
