Scenarios, procedures, and intent types

Scenarios, procedures, and intent types are three interconnected systems that define and execute conversation paths in the NAF. Scenarios define the step-by-step scripts the ConvoAgent follows. Procedures provide reusable instruction blocks that scenarios reference. Intent types route incoming conversations to the correct scenario based on the user's request and business hours. This article covers both the developer-facing formatting basics and the internal pipelines: the ScenarioWriter multi-agent system, the canvas builder's procedure library, and the compiled intent type map.

System overview

User calls with a request
    │
    ▼
Introduction scenario (Scenario 0)
    │  Identifies user intent
    ▼
Intent Type Map (ITM)
    │  Routes to correct scenario based on intent + working hours
    ▼
Target scenario (e.g., Scenario 1: "Make a Regular Table Booking")
    │  Steps reference procedures for data collection
    ▼
Procedures (e.g., "Gathering Phone Number")
    │  Provide reusable step-by-step instructions
    ▼
Critical steps with code-phrases
    │  Trigger Tool Caller actions (e.g., "Let me check availability...")
    ▼
Tool execution (booking, SMS, email, transfer)

The Observer's thought generation (_genThoughtsSkill) cross-references all three systems to produce KEY DIRECTIVES — the step-by-step instructions that tell the ConvoAgent exactly what to do next.

Scenario basics

A scenario is a structured markdown document that defines a conversation path. Each scenario has a trigger, numbered steps, and optional decision branches.

Scenario format

## **Scenario 1:** "Make a Regular Table Booking"

This scenario starts when the user wants to make a reservation
for a small party.

### **Step 1.1:** Follow the **Gathering Phone Number** procedure.

### **Step 1.2:** Follow the **Gathering Full Name** procedure.

### **Step 1.3:** Follow the **Gathering Preferred Date and Time** procedure.

### **Step 1.4:** Confirm the reservation details with the user.

### **Step 1.5:** **CRITICAL STEP!!!** Say the special **code-phrase**:
**"Let me check availability for [[preferred_date]] at [[preferred_time]]"**

### **Step 1.6:** Decide how to proceed based on the availability result:
- If available: Tell the user the booking is confirmed.
- If not available: Suggest alternative times.

### **Step 1.7:** Proceed with the **Finish Conversation** scenario.

Structural elements

Cross-scenario transitions

Steps can reference other scenarios by name. The Observer uses the Intent Type Map to resolve which scenario to start:

### **Step 0.1:** Decide how to proceed based on the user's intent:
- If the user wants to make a reservation: ConvoAgent starts the scenario:
    **"Make a Regular Table Booking"**.
- If the user wants to cancel: ConvoAgent starts the scenario:
    **"Regular Transfer"**.

The ScenarioWriter

The platform includes an AI-assisted ScenarioWriter that generates properly formatted scenarios from a natural language description. When you request a new scenario in the platform, the ScenarioWriter analyzes the request, builds a structured step sequence, maps steps to available procedures from the canvas library, and formats the result into the scenario markdown format described in this article. After initial generation, you can refine the scenario through a conversational editing loop until you're satisfied with the output.

Critical steps and code-phrases

Critical steps are the bridge between scenarios and the Tool Caller. When the ConvoAgent says a code-phrase, the Tool Caller detects the commitment and triggers the corresponding backend action.

How code-phrases trigger tools

Scenario step: **CRITICAL STEP!!!** Say the special **code-phrase**:
    **"Let me check availability for [date] at [time]"**
        │
        ▼
ConvoAgent says: "Let me check availability for Friday at 7 PM"
        │
        ▼
Tool Caller: get_tools_to_call analyzes the latest answer
        │  Detects: subject="I" (agent), verb="check", keyword="availability"
        │  Matches: check_availability_tool conditions
        ▼
Tool execution: CACheckingAvailabilityFlow runs

Fixed phrases vs keyword-based phrases

The Observer's thought generation ensures code-phrases are always included in the KEY DIRECTIVES when the corresponding step is active:

"If you see a specific code-phrase in the step, you must say it." — _genThoughtsSkill instruction rule #2

Procedure basics

A procedure is a reusable block of step-by-step instructions that multiple scenarios can reference. Instead of repeating "ask for the phone number, validate it, handle country codes..." in every scenario, the scenario simply says Follow the **Gathering Phone Number** procedure.

Procedure format

## **Gathering Phone Number** procedure

1. Ask the user for their phone number.
2. If the user provides a number, confirm it by reading it back.
3. If the user says the number is correct, proceed to the next step.
4. If the user says the number is incorrect, ask again.

> [!NOTE]
- If the phone number was already detected from caller ID,
    ask the user to confirm it instead of asking for it from scratch.

Procedure storage

Procedures are stored in the canvas library — a structured repository within the platform that the ScenarioWriter reads when mapping procedures to steps.

Procedure library management

The GMcanvasBuilderFlow in the GeneralManagerAgent manages the canvas library. It provides skills for:

• Adding, updating, and deleting library items
• Filtering and navigating library contents
• Generating template procedures from industry defaults

Uninterruptible scenario phases

Some steps or groups of steps in a scenario can be marked as an Uninterruptible Scenario Phase. When the Observer detects that the current step has this flag, it instructs the ConvoAgent to refuse topic changes and strictly complete all tasks in the marked steps.

The Observer's KEY DIRECTIVES include an example response for handling user deviations:

**Uninterruptible Scenario Phase!** ConvoAgent must refuse to change
the conversation topic at this stage. ConvoAgent must strictly follow
the KEY DIRECTIVES. If the user changes the topic, let them know that
[main goal] will not happen if the topic changes. Example response:
"David, I suggest completing the booking before switching to a different
topic, otherwise the reservation will not be processed. So can I ask
your last question again?"

This mechanism prevents situations where a user derails a multi-step process (e.g., booking) mid-way, which would leave the system in an incomplete state.

Introduction scenario

Scenario 0 ("Introduction") is a special scenario that runs at the start of every conversation. Its purpose is to:

1. Greet the user.
2. Identify the user's intent.
3. Route to the correct scenario based on the Intent Type Map.

## **Scenario 0:** "Introduction"

This scenario starts when a new conversation begins.

### **Step 0.1:** Greet the user and ask how you can help.

### **Step 0.2:** Decide how to proceed based on the user's intent
and the **IntentTypeMap**:
- If the user wants to make a reservation for fewer than 7 guests:
    Start **Scenario 1: "Make a Regular Table Booking"**.
- If the user wants a large reservation:
    Start **Scenario 3: "Large Reservation"**.
- If the user wants to cancel:
    Start **Scenario 5: "Regular Transfer"**.

The Observer generates KEY DIRECTIVES that include the Introduction scenario's branching logic, guiding the ConvoAgent to ask the right questions to identify the intent.

Intent types

Intent types classify incoming conversations and route them to the correct scenario. Each intent type defines a trigger condition, the scenario to start, and whether the session is a lead ([L]), a transfer ([T]), or unclassified.

Intent type structure

Each intent type is a JSON object with the following fields:

{
  "idn": "intent_type_make_regular_table_booking",
  "title": "## **[L] Regular Table Booking**",
  "body": "A guest wants to make a reservation for a party of fewer than
    **[[minimum_party_size]]** guests.\nConvoAgent starts the scenario:
    **\"Make a Regular Table Booking\"**.",
  "is_from_library": true,
  "origin_idn": "",
  "description": "Small-party reservation handled directly by ConvoAgent.",
  "mentions": [
    {
      "type": "scenarios",
      "item_idn": "scenario_restaurant_regular_reservation_default"
    }
  ]
}

Intent type classification

Working hours routing

Intent types support dual routing based on business hours. The same intent type can specify different behavior for working hours vs non-working hours:

A guest wants to make a reservation for a large party.
During Working Hours: ConvoAgent starts the scenario:
    **"Make a Large Reservation"** and then proceeds with
    **"Regular Transfer"**.
During Non-Working Hours: ConvoAgent starts the scenario:
    **"Make a Large Reservation"**.

The platform compiles two separate intent type maps:

Intent type map retrieval

The _getIntentTypeMapSkill selects the correct compiled map based on current business hours.

The compiled map is injected into the supervisor context as the <IntentTypeMap> block, where the Observer uses it to generate routing directives.

Industry-specific intent type libraries

The NAF ships with pre-built intent type libraries for eight industries. Each library defines the standard intent types, classifications, and scenario references for that industry.

Common intent types

All industries share these standard intent types:

Additionally, a shared library_intent_types_common_appointment_agent intent type ([L] Appointment via Agent) is available across all industries for scheduling appointments directly through the ConvoAgent.

Example: full intent-to-scenario flow

Here is an end-to-end walkthrough from an incoming call to tool execution:

1. User calls. The platform fires conversation_started and the ConvoAgent begins Scenario 0: "Introduction."

2. User says: "Hi, I'd like to book a table for 4 people this Friday."

3. Observer runs. The _getIntentTypeMapSkill checks working hours (business is open → uses working hours ITM). The _genThoughtsSkill generates KEY DIRECTIVES:

## Scenario 0: "Introduction"

- **Step 0.1:** The user has already stated their intent. Route to the
    appropriate scenario based on the IntentTypeMap.
    - **[L] Regular Table Booking**: A guest wants to make a reservation
        for fewer than 7 guests → Start **Scenario 1: "Make a Regular
        Table Booking"**, **Step 1.1:** Follow the **Gathering Phone
        Number** procedure.

4. ConvoAgent responds: "Great! I'd be happy to help you book a table. May I have your phone number, please?"

5. User provides phone number. Observer updates field tracking:

   • FIELDS SUCCESSFULLY COLLECTED: Phone Number: 5551234567 (gathered)
   • FIELDS TO BE COLLECTED: Full Name: not known

6. Observer generates new KEY DIRECTIVES:

## Scenario 1: "Make a Regular Table Booking"

- 1.2: Follow the **Gathering Full Name** procedure.
- 1.3: Follow the **Gathering Preferred Date and Time** procedure.
    Since preferred date (Friday) and time are already known, this step
    may be skipped or used for reconfirmation.
- 1.4: Confirm reservation details with the user.

7. After collecting all fields, the Observer reaches the critical step:

- 1.5: **CRITICAL STEP!!!** Say the special **code-phrase**:
    "Let me check availability for Friday at 7 PM"

8. ConvoAgent says the code-phrase. The Tool Caller detects check_availability_tool conditions are met and fires the CACheckingAvailabilityFlow.

9. Availability result returns. The Observer updates the <AvailabilityForTheUserRequestedDateTime> section and generates new directives based on the result (available → confirm booking, not available → suggest alternatives).

10. Conversation continues through remaining steps until the end_conversation_tool detects mutual farewell and terminates the session.

Changelog

Scenarios, procedures, and intent types: initial publication

Published developer reference covering scenario format and structural elements, the ScenarioWriter multi-agent pipeline (5 agents: analyze, draft, map procedures, format, edit), critical steps and code-phrase mechanics, procedure storage in the canvas library, intent type structure and classification ([L]/[T]), working hours routing with dual compiled ITMs, industry-specific intent type libraries for 8 industries, and a full end-to-end intent-to-scenario flow example.