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.

Transition tools are simple tools whose only purpose is to transition to a new node.

​
Create a transition tool

​
Attach via JSON

Use a function with type: "transition" and set transition_to to the destination node. 
{
  "name": "<transition_tool_name>",
  "description": "<description>",
  "type": "transition",
  "transition_to": "<TARGET_NODE_NAME>"
}
For example: 
{
  "name": "continue_to_verification",
  "description": "Use this tool after the prospect confirms their details to move to the appointment booking node",
  "type": "transition",
  "transition_to": "appointment_booking"
}

​
Attach via UI

  1. Open your scenario and go to the target node.
  2. Click Add function.
  3. Select the Transition Tool tab in the pop up modal
  4. Enter a name and description the model will use to decide when to call this tool. Use a short, unique name (often snake_case, e.g. continue_to_booking) with no spaces—same idea as in JSON. The description should say when to invoke the tool (what the user said or what must be true first), not just what the tool does—for example: “After the user confirms their email, move to booking,” so the assistant does not jump nodes too early.
  5. Drag the probe on the right side of the function to the node you wish to transition to.

​
Require function call

For nodes that require a function call, we recommend that the required tool transitions the flow to another node. If the user remains on the same node, every LLM turn will still invoke the required tool. That may be appropriate for tools you mean to reuse every turn (such as a RAG tool before every bot response), but may not be appropriate for other tools.

​
Require reason

Set require_reason: true on a transition function to make the LLM pass a reason argument whenever it calls the tool. The reason shows up in the tool-call payload in the conversation transcript, so you can see why the model chose to transition. 
{
  "name": "continue_to_verification",
  "description": "Use this tool after the prospect confirms their details to move to the appointment booking node",
  "type": "transition",
  "transition_to": "appointment_booking",
  "require_reason": true
}
We recommend enabling require_reason during development to make transition behavior easier to diagnose. Because the model must generate an additional reason field on each call, it introduces a small latency cost, so whether to keep it enabled in production is a trade-off you should make based on your application’s latency requirements.
require_reason is only valid on type: "transition" functions.

​
Make any tool a transition tool

Any tool can also be configured to transition after it is called, including HTTP endpoints, RAG tools, and vision tools. To do this in JSON, set transition_to on that tool function object. 
{
  "name": "lookup_policy_and_continue",
  "description": "Search policy details, then move to verification.",
  "type": "rag",
  "knowledge_base_id": "<KNOWLEDGE_BASE_ID>",
  "transition_to": "verification"
}
In the UI, drag the function to the node you want to transition to after that tool is called.

​
Dynamic HTTP transitions

HTTP endpoints can also use dynamic transition logic instead of a fixed transition_to target. With dynamic HTTP transitions, the tool defines allowed_next_nodes, and Akapulu reads next_node from the endpoint’s JSON response to decide which node to enter next. To learn how dynamic HTTP routing works, including the next_node response contract and error behavior, see Endpoints.