Workflow: Transitions Between States

State transitions define the possible paths between states. This article explains how to create transitions. For more information on what a state is and what it does, refer to the Workflow Basics article.

---

Basic Transition Structure

There can be more than one transition between two states. Each transition describes when the agent moves to another state. The agent selects one of these transitions based on the conversation context.

state_scenarios:
  - next_state: CollectionState
    transition_name: verify_identity
    description: "Move to collection after confirming identity"
    attached_tools:
      - SendVerificationTemplate
  
  - next_state: ScheduleReminder
    transition_name: begin_schedule_reminder
    description: "Schedule a reminder if human is busy"

Field	What it does	Example	Required
next_state	The next state for the agent to move to	CollectingInformation	Yes
transition_name	A name for this transition — helps the agent understand the transition logic. Can be used to analyze Trace logs analytics when testing the agent	CustomerGreeted	Yes
description	Conditions and triggers when to make this transition	"Move to information collection..."	Yes
attached_tools	Additional tools available during transition	[SendVerificationTemplate]	No
transition_observation	Optional note about the outcome	"Customer has acknowledged greeting."	No

Each transition must reference an existing state through next_state. The description should clearly explain when the agent should choose that transition.

Transitions Example

The following YAML example shows workflow transitions:

- process_name: CollectionProcess
  name: GreetingState
  kind: StateConfig
  init_state: true
  ...

  state_scenarios:
    - next_state: CollectionState
      transition_name: verify_identity
      description: "Move to collection after confirming identity"
      attached_tools:
        - SendVerificationTemplate

    - next_state: ScheduleReminder
      transition_name: begin_schedule_reminder
      description: "Schedule a callback if human is busy"

- process_name: CollectionProcess
  name: CollectionState
  kind: StateConfig
  ...

- process_name: CollectionProcess
  name: ScheduleReminder
  kind: StateConfig
  ...

In the diagram, the agent starts the collection process if the customer doesn't indicate that their a busy. But the agent can only move to CollectionState after it verifies customer's identity. If the customer is busy, the agent moves to ScheduleReminder to arrange a new interaction.

Transition Design Tips

Avoid overlapping conditions, where two transitions could apply to the same situation — the agent may stuck in loop or choose the wrong transition.

Clear ✅	Problematic ❌
- verify_identity: "When customer confirms they are the correct person" - end_wrong_person: "When customer says they are not the target person"	- verify_identity: "When identity is confirmed" - proceed_to_collection: "When ready to discuss payment"

---

Next Steps

• Checklist and Testing