Skip to main content

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 are how you control assistant behavior in Akapulu. 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 Akapulu works.

​
Nodes

Akapulu implements these stages using nodes. A node contains stage instructions plus the tools the assistant can use in that stage. The model can move between nodes using transition tools. Example of two connected scenario nodes Akapulu 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 supports the following OpenAI models. For official specifications and pricing, see OpenAI’s model documentation.
ModelAvailable on Free tier
GPT-4.1 nanoYes
GPT-4.1 miniYes
GPT-4o miniYes
GPT-5.4 nanoYes
GPT-5.4 miniYes
GPT-4.1No*
GPT-4oNo*
GPT-5.4No*
* 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.

​
Role and task instructions

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

​
Create scenario walkthrough

​
Create a simple node

  1. Go to the Scenarios page.
  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. 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.
The first node you create is the default start node. Each scenario has exactly one start node.

​
Edit an existing scenario

​
Add another node

  1. Click Add Node.
  2. Enter a node name:
    • Planning Phase
  3. Add a task instruction:
Help the user plan their project on the Akapulu platform

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

​
Add tools and transitions

You can add tools directly to each node.

​
Create the RAG tool

  1. Create a Knowledge Base.
  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 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, 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 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. 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. 
{
  "initial_node": "Greeting",
  "role_instruction": "You are a helpful Akapulu 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. 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, 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 platform. Use the knowledge base tool when you need platform information.",
      "functions": [
        {
          "name": "Akapulu_RAG",
          "description": "Access information on the Akapulu 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