Authoring routines

Building routines node by node: the golden rule, transitions and branching, tool chains, loops, common patterns, anti-patterns, and the pre-submit checklist.

Context — This guide assumes the Routines concept page (node kinds, classification, completion semantics). Here we build up a real routine and collect the patterns that keep flows reliable.

YAML examples follow manifest schema 6.1.5. Manifest and content shapes are schema-versioned and differ across runtime versions — see Versioning & compatibility.

The golden rule

A node does exactly one thing. It calls tools, or speaks, or routes. Never two of these at once. (A fourth kind — the typed-inference THINK node — belongs to autonomous routines, not conversational ones.)

Wrong — the schema rejects tools + chat_state on one node, and for good reason:

  - id: handoff
    tools: crm:initiate_human_handoff
    tool_instruction: "Initiate human handoff."
    chat_state: "Inform the customer they are being transferred."  # REJECTED

Right — two nodes connected by a transition:

  - id: handoff-tool
    tools: crm:initiate_human_handoff
    tool_instruction: "Initiate human handoff."
    transitions:
      - to: handoff-msg

  - id: handoff-msg
    chat_state: >
      Inform the customer they are being transferred to a human agent.

Activation conditions

conditions decide when the whole routine engages. Same craft as policy conditions: concrete phrasings, explicit boundaries against sibling routines.

conditions:
  - >
    The user wants to make a reservation — phrases like "I want to book
    this", "let's reserve the Golf", "can you book it". Activates after
    the user has identified a specific car, or when they explicitly name
    a make/model they want to rent.

A booking routine and a search routine live side by side precisely because each condition names its own triggers and excludes the other's ("Do NOT activate when the user is referring to a specific booking they already have").

Conditions and chat_state texts reach the model exactly as authored, so YAML block style matters — see policy rule 4 for when to use a literal block (|) versus a folded block (>).

The graph: entry, transitions, terminals

Execution starts at the node named by entry. Edges live on the node that produces them:

entry: ask-dates
nodes:
  - id: ask-dates
    chat_state: >
      Ask for the pickup date and return date in one short message.
    transitions:
      - to: fetch-availability
        condition: "The user has provided both dates."

  - id: fetch-availability
    tools: cars:check_availability
    tool_instruction: >
      Call check_availability with pickup_date and return_date as
      YYYY-MM-DD strings.
    transitions:
      - to: present-availability

  - id: present-availability
    chat_state: >
      Present the available cars for those dates with daily prices in EUR.

The rules to internalise:

• One transition → condition optional (unconditional advance).

• Two or more transitions → every one needs a condition. The engine evaluates them and takes the matching branch.

• No transitions at all → terminal node. The routine completes there.

• Loops are first-class. Transition back to an earlier node id to re-ask until the answer validates — no special syntax.

Tool nodes: instructions are parameter maps

tool_instruction tells the model how to call the tool — which arguments, derived from where, in what format. It is not customer-facing and should contain zero messaging:

  - id: create-the-booking
    tools: cars:create_booking
    tool_instruction: >
      Call create_booking with all collected fields. Pass car_id,
      pickup_location, pickup_date and return_date (YYYY-MM-DD strings),
      customer_name, driver_age. Pass extras as a list of extra_ids from
      list_extras (omit if none). Pass member_email only if the member
      lookup succeeded.
    transitions:
      - to: announce-result

Multiple sequential tools chain naturally (each tool node advances in the same turn). Independent tools can share one node:

  - id: fetch-data
    tools:
      - cars:get_booking_history
      - cars:get_loyalty_status
    tool_instruction: >
      Get the customer's past bookings and their loyalty status using the
      customer id. Execute both in parallel.
    transitions:
      - to: present-findings

Branching: conditions on transitions

The flow splits wherever a node declares multiple conditioned transitions. Action nodes can branch directly:

  - id: fetch-status
    tools: crm:get_account_status
    tool_instruction: "Get the account status using PARTYID."
    transitions:
      - to: active-path
        condition: "account status is ACTIVE"
      - to: suspended-path
        condition: "account status is SUSPENDED"

  - id: active-path
    chat_state: "Tell the customer their account is in good standing."

  - id: suspended-path
    chat_state: >
      Explain the account is suspended and offer to connect them with a
      human agent.

When a decision point needs no action of its own, use a routing-only node (transitions, no action):

  - id: triage
    transitions:
      - to: vip-flow
        condition: "the customer's loyalty_tier is gold or platinum"
      - to: standard-flow
        condition: "the customer has no premium loyalty tier"

Asking the customer and acting on the answer

A chat node whose transitions depend on the customer's reply is the question-and-dispatch idiom:

  - id: ask-resubmit
    chat_state: >
      Ask the customer if they would like to resubmit their documents.
    transitions:
      - to: generate-link
        condition: "The customer wants to resubmit"
      - to: acknowledge-no
        condition: "The customer does not want to resubmit"

  - id: generate-link
    tools: crm:generate_upload_link
    tool_instruction: "Generate a document upload link using PARTYID."
    transitions:
      - to: share-link

  - id: share-link
    chat_state: "Share the upload link with the customer."

  - id: acknowledge-no
    chat_state: "Acknowledge and offer further help."

The engine waits on the customer after ask-resubmit (the transitions depend on their answer), then takes the matching branch — possibly several turns later, and it can backtrack if they change their mind.

Reusable wording: macro interpolation

When the same explanation must appear verbatim in several flows, publish it as a macro, pin it in the manifest's context.macros, and interpolate it inside chat_state with ${macro-id}:

  - id: explain-cancellation
    chat_state: |
      Here's how cancellation works for your booking:

      ${cancellation-policy}

      Would you like me to go ahead and cancel it?
    transitions:
      - to: await-decision

Only chat_state interpolates macros — tool_instruction and description take literal text.

Anti-patterns

Anti-pattern	Symptom	Fix
Tools + chat_state on one node	Schema rejects it	Split into tool node + chat node connected by a transition
Messaging inside tool_instruction	Tone leaks into tool calls; replies appear before data arrives	Move messaging to the following chat node
Conditions narrating actions ("ask the user X if…")	Transitions that half-do things	Conditions gate; actions act
Mega-nodes ("collect dates, search, present, and offer extras")	The model freelances the ordering	One concern per node
Two chat nodes with no customer-dependent transition between them	Second one never runs in the same turn	Merge the messages or make the dependency explicit
Duplicating a global rule in every routine	Drift between copies	Make it a policy
Deep tool chains exceeding the iteration cap	Turn ends mid-flow / autonomous runs fail with max_engine_iterations_reached	Shorten, parallelise independent tools, or raise runtime.max_engine_iterations
Unconditioned multi-way branches	Schema rejects 2+ transitions without conditions	Condition every branch explicitly

Testing a routine

1. Deploy it to a staging agent against a stub MCP server (the Quickstart builds one end to end) and walk the happy path through the chat UI.

2. Probe each branch: phrase inputs that should take every transition, including the "changed my mind" backtrack.

3. Watch the trace for the turn — it shows activation, node selection, and each tool call; see Observability.

4. Check boot output: every routine logs Routine '<title>' evaluated: N nodes in Xs at startup — failures there mean structural problems.

Pre-submit checklist

• entry names a declared node; every transitions[].to resolves

• No node combines tools with chat_state

• Every tool node that needs customer-facing output transitions to a chat node

• tool_instruction is parameter mapping, not messaging

• Every multi-way branch conditions all of its transitions

• Node ids unique

• Terminal nodes are intentional (no transitions means the routine ends there)

• Activation conditions name concrete triggers and exclude sibling routines

• Longest tool chain fits within max_engine_iterations

• Every ${macro-id} in chat_state is pinned in context.macros