Configuration

A bot is one YAML artifact plus whatever scripts it needs. The YAML declares structure; scripts handle logic that declaration cannot express. Simple things stay simple, complex things stay possible.

The bot definition

kind: bot
metadata:
  name: acme-support
  tenant: acme
  product: support-portal
  version: 7

spec:
  channels:
    - kind: web
      enabled: true
    - kind: slack
      enabled: true
      workspace_ref: vault:acme/slack-token
    - kind: whatsapp
      enabled: true
      account_ref: vault:acme/whatsapp-account
      templates_ref: registry:acme/whatsapp-templates

  persona:
    prompt_ref: gateway:acme-support-persona-v7
    style: professional
    locale_default: en-US
    locales: [en-US, es-MX, pt-BR]

  preprocess:
    - script: scripts/normalize.js
    - script: scripts/enrich_user.lua     # look up the user in your CRM

  nlu:
    cascade:
      - stage: rules
        enabled: true
        confidence_threshold: 0.95
        rules_ref: rules/intents.yaml
        custom_script: scripts/complex_match.lua
      - stage: dynamic_model
        enabled: true
        confidence_threshold: 0.90
        model_ref: ai-ml:acme-support-dynamic-v7
      - stage: classifier
        enabled: true
        confidence_threshold: 0.85
        model_ref: ai-ml:acme-support-classifier-v7
      - stage: slm
        enabled: true
        confidence_threshold: 0.80
        model_ref: gateway:acme-support-slm-v3
      - stage: llm
        enabled: true
        confidence_threshold: 0.0        # terminal
        model_ref: gateway:acme-support-llm-default
    calibration_ref: registry:acme-support-calibration-v7

  orchestrate:
    handlers:
      - intent: business_hours
        path: canned
      - intent: order_status
        path: skill
        skill_ref: ai-computer:acme-order-lookup-v2
      - intent: refund_request
        path: flow
        flow_ref: acme-refund-workflow

Channels

Every channel is off unless declared. Credentials are always vault references — a token in this file is a token in your git history.

Channel	Required reference
`web`	none
`slack`	`workspace_ref`
`teams`	`app_ref`
`whatsapp`	`account_ref`, `templates_ref`

WhatsApp additionally needs pre-approved message templates for anything you send outside a user-initiated window; that is a platform rule of WhatsApp’s, not of this block.

Cascade stages

Stages run in the order listed. Each takes:

enabled — a disabled stage is skipped entirely, and messages escalate past it
confidence_threshold — the calibrated probability-of-correctness required to stop here
model_ref — where the stage’s model lives (ai-ml: for generated models, gateway: for gateway aliases)

Thresholds are statements about acceptable accuracy. 0.85 means “stop here if this resolution is at least 85% likely to be right”, and that means the same thing at every stage because of calibration. See Core Concepts.

Start conservative. High thresholds send more traffic to expensive stages but keep quality up; lower them once eval data shows a stage is trustworthy at that level. Tuning thresholds against production outcomes is more reliable than guessing them up front.

Handlers

orchestrate.handlers maps an intent to a resolution path. Intents with no handler fall to the default generative path.

handlers:
  - intent: business_hours
    path: canned              # answered from the rules, no model call

  - intent: order_status
    path: skill               # call a skill and return its result
    skill_ref: ai-computer:acme-order-lookup-v2

  - intent: product_question
    path: rag                 # retrieve, then generate a grounded answer
    collection: acme-product-docs

  - intent: refund_request
    path: flow                # bounded multi-step autonomous work
    flow_ref: acme-refund-workflow

Script hooks

Where declaration runs out, scripts attach at defined points:

Hook	Runs	Typical use
`preprocess`	Before NLU	Normalisation, enriching the user from your systems
`nlu` (rules stage)	During stage 1	Matching too complex for declarative regex
`orchestrate`	Choosing a response	Custom routing, calling internal systems
`escalate`	On escalation	Custom escalation decisions
`postprocess`	Before sending	Formatting, injecting dynamic content
`fallback`	Unrecognised intent	Graceful catch-all behaviour

Scripts see a rich binding surface:

msg.*        incoming message: text, attachments, metadata, channel, locale
conv.*       conversation: turn count, history, current stage, age
user.*       identity: id, attributes, authenticated, locale, prior context
channel.*    channel kind, capabilities, formatting constraints
respond.*    emit a response: text, cards, buttons, quick replies, streaming
state.*      read/write conversation variables, transition the state machine
nlu.*        cascade results: intent, entities, confidence, resolving stage
escalate.*   trigger escalation, set reason and target
ai.*         model calls, routed through the AI Gateway
mem.*        memory access
know.*       knowledge retrieval
tool.*       tool dispatch
log.*        structured logging
meta.*       tenant, product, bot id, request id, purpose

Note that ai.* goes through the gateway like everything else — a script cannot bypass budgets or accounting by calling a provider directly.

Operations — the build pipeline, analytics and compliance