> ## Documentation Index
> Fetch the complete documentation index at: https://docs.akapulu.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Scenarios Overview

> Learn how to design conversation flows using stages, tools, and node transitions.

Scenarios are how you control assistant behavior in Akapulu Labs.

When you start a conversation, the scenario provides:

* a global `role_instruction`
* node-specific `task_instruction` prompts
* tool access (transitions, HTTP tools, RAG, vision)
* flow logic for how the conversation moves between stages

For most real conversations, a single static prompt is not enough. The assistant often needs different instructions and tools at different moments.

## Scenarios and conversation stages

A scenario lets you design the flow as a set of stages. At each stage, you can decide:

* what the assistant should focus on
* how it should respond
* which tools it can use

As the conversation evolves, the assistant transitions between stages when appropriate.

For walkthrough-style examples with diagrams (interview coach and patient intake flows), see [How it works](/guides/getting-started/how-akapulu-works#scenarios-and-conversation-stages).

## Nodes

Akapulu Labs implements these stages using [nodes](/guides/scenarios/node-basics). A node contains stage instructions plus the tools the assistant can use in that stage.

The model can move between nodes using transition tools.

<img src="https://mintcdn.com/akapulu/CiHIhUHKoEfRGs56/images/guides/getting-started/How-akapulu-works/node-diagram/intro-data-intake.svg?fit=max&auto=format&n=CiHIhUHKoEfRGs56&q=85&s=e2621db59cf070a535d0aa3f2e4fca54" alt="Example of two connected scenario nodes" style={{ borderRadius: 12, margin: "0 auto", display: "block" }} width="879" height="348" data-path="images/guides/getting-started/How-akapulu-works/node-diagram/intro-data-intake.svg" />

Akapulu Labs provides a drag-and-drop UI for building and connecting nodes.

## Choosing the LLM model

You can control which underlying LLM generates the bot’s responses for that scenario. In the node editor, open the **Scenario Menu** on the left, go to **Settings**, and choose **LLM model**.

Akapulu Labs supports the following OpenAI models. For official specifications and pricing, see [OpenAI’s model documentation](https://platform.openai.com/docs/models).

| Model        | Available on Free tier |
| ------------ | ---------------------- |
| GPT-4.1 nano | Yes                    |
| GPT-4.1 mini | Yes                    |
| GPT-5.4 nano | Yes                    |
| GPT-5.4 mini | Yes                    |
| GPT-4.1      | No\*                   |
| GPT-5.4      | No\*                   |

\* Requires a paid subscription.

## Testing the scenario

Use the **Testing Mode** tab in the Scenario Menu to run an **LLM-only, text-based simulation** of the scenario in the editor.

Test sessions **do not count toward** your plan’s voice or video **minute allowance**.

For setup, limits, and behavior, see [Testing Mode](/guides/scenarios/llm-test-mode).

To run the scenario as a **full live avatar conversation** you can share with anyone (no SDK or backend required), use the **Hosted Link** tab. See [Hosted Links](/guides/scenarios/hosted-links).

## Role and task instructions

Akapulu Labs combines a global **role instruction** with each node’s **task instruction** to decide what the model should do at every stage. For how that context is assembled and how to write both fields, see [Role and task instructions](/guides/scenarios/role-and-task-instructions).

## Create scenario walkthrough

### Create a simple node

1. Go to the [Scenarios page](https://akapulu.com/scenarios).
2. Click **New**.
3. Enter the scenario name.
4. Open the **Scenario Menu** from the **left** side of the editor (hamburger icon) so the side panel opens. Stay on the **Settings** tab.
5. Edit the global **role instruction** in the text area.
   * Example: `You are an onboarding assistant for Akapulu Labs. Keep responses concise because they will be converted to audio.`
6. In the same **Settings** tab, open the **LLM model** dropdown and pick the desired llm model (we recommend leaving it as GPT-4.1 Mini)
7. Click **Add Node** to create your first node.
8. Enter a node name (for example, `Greeting`).
9. Add a node **task instruction**.
   * Example: `Greet the user, ask what they want to build, and keep your response concise.`

<Note>
  The first node you create is the default **start node**. Each scenario has exactly **one** start node.
</Note>

## Edit an existing scenario

### Add another node

1. Click **Add Node**.
2. Enter a node name:
   * `Planning Phase`
3. Add a task instruction:

```text theme={null}
Help the user plan their project on the Akapulu Labs platform

Use your Akapulu RAG tool to get information on how Akapulu Labs works
```

## Add tools and transitions

You can add tools directly to each node.

### Create the RAG tool

1. Create a **[Knowledge Base](/guides/knowledge-bases/overview)**.
2. Back in the scenario editor, click **+ Add function** at the bottom of the **Planning Phase** node.
3. In the pop up modal, open the **RAG Tool** tab.
4. Select your knowledge base, then create the RAG function with:
   * **Name:** `Akapulu_RAG`
   * **Description:** `Access information on the Akapulu Labs platform`

**What you accomplished:** You wired your knowledge base into the **Planning Phase** node as a callable RAG function named `Akapulu_RAG`.

**What this means for the bot:** While the conversation is in **Planning Phase**, the model can invoke that function to pull retrieval-augmented context from your knowledge base. Its replies in that stage can lean on grounded snippets instead of guessing, which matches the node’s task instruction to use the Akapulu RAG tool when explaining the platform overview.

### Create the transition tool

1. In the scenario editor, click **+ Add function** at the bottom of the **Greeting** node.
2. In the pop up modal, open the **Transition Tool** tab.
3. Create a transition function with:
   * **Name:** `transition_to_planning_phase`
   * **Description:** `Once you have gathered enough information on what the user wants to build with Akapulu Labs, use this tool to transition to the planning phase`
4. Drag the probe on the right side of `transition_to_planning_phase` to the **Planning Phase** node to set the transition target.

**What you accomplished:** You gave the **Greeting** node an explicit transition tool that moves the flow into **Planning Phase** when the model chooses to call it.

**What this means for the bot:** During **Greeting**, the assistant follows the greeting task instruction and only has the transition tool (not RAG yet). When it decides enough context has been collected, it can call `transition_to_planning_phase`, and Akapulu Labs switches the active node: **Planning Phase** task instructions are added to the llm context, and `Akapulu_RAG` becomes available so behavior shifts from discovery to informed planning overview.

## Completed scenario example

You have now built a simple scenario.

This scenario starts in `Greeting`, where the assistant asks open-ended questions about what the user wants to build with Akapulu Labs. Once project scope is clear, it calls `transition_to_planning_phase` and moves into `Planning Phase`, where `Akapulu_RAG` is available to pull platform information and help shape the user’s plan.

If you want to view or edit this scenario as JSON, use the scenario editor toggle in the top-right corner to switch between visual mode and JSON mode.

```json theme={null}
{
  "initial_node": "Greeting",
  "role_instruction": "You are a helpful Akapulu Labs onboarding assistant. Keep responses concise because they will be converted to audio.",
  "nodes": {
    "Greeting": {
      "task_instruction": "Ask open-ended questions to understand what the user wants to build with Akapulu Labs. Once project scope is clear, use the transition tool to move to planning.",
      "functions": [
        {
          "name": "transition_to_planning_phase",
          "description": "Once you have gathered enough information on what the user wants to build with Akapulu Labs, use this tool to transition to the planning phase",
          "type": "transition",
          "transition_to": "Planning Phase"
        }
      ]
    },
    "Planning Phase": {
      "task_instruction": "Help the user plan their project on the Akapulu Labs platform. Use the knowledge base tool when you need platform information.",
      "functions": [
        {
          "name": "Akapulu_RAG",
          "description": "Access information on the Akapulu Labs platform",
          "type": "rag",
          "knowledge_base_id": "<KNOWLEDGE_BASE_ID>"
        }
      ]
    }
  }
}
```

***

The scenario editor has **view** mode and **edit** mode for each scenario.

Starting from **New** opens **edit** mode by default, so you can add nodes, edit instructions, and configure tools immediately.

Opening a scenario from the scenarios table opens **view** mode first. In view mode you can review the flow, but you cannot change the graph or tool wiring. Click **Edit** in the lower-left corner to switch to **edit** mode and make those changes.

## Next scenario guides

* [Role and task instructions](/guides/scenarios/role-and-task-instructions)
* [Testing Mode](/guides/scenarios/llm-test-mode)
* [Hosted Links](/guides/scenarios/hosted-links)
* [Using JSON](/guides/scenarios/using-json)
* [Node basics](/guides/scenarios/node-basics)