Configure the workflow

The Workflow section defines the conversation flow as a state machine in YAML. This page covers states, transitions, the diagram preview, and how to test changes.

Configure the workflow

The Workflow section defines the conversation flow as a state machine in YAML. Each state is one phase of the conversation with its own instructions and tools; the agent operates in exactly one state at a time and moves between states through transitions.

New agents come with a default workflow that supports the Simple mode features. Customize the workflow when you need:

• A strict multi-step process — for example, verify identity before discussing an account.
• Different instructions or tools at different stages of the conversation.
• Controlled escalation paths, such as a transfer to a human after repeated failures.

Fewer states make the agent more flexible; more states make it more predictable. Start with one or two states and add more only when needed.

tip

The ? icon in the Workflow section header opens the formatting reference for the YAML syntax.

Define states

Each state is one list item in the YAML:

- process_name: SupportProcess
  name: Greeting
  kind: StateConfig
  init_state: true

  description: |
    - Greet the human
    - Ask how you can help
    - Determine human intent

  available_tools:
    SingleStatefulOutboundAgent:
      - SendChatMessage

  state_scenarios:
    - next_state: Answer
      transition_name: human_question_received
      description: "human asks a question"

- process_name: SupportProcess
  name: Answer
  kind: StateConfig
  final_state: true

  description: |
    - Answer the human's question
    - Ask if additional help is needed
    - End the conversation

  available_tools:
    SingleStatefulOutboundAgent:
      - SendChatMessage
      - FinishSession

Field	What it does	Required
process_name	Groups related states into a process. Usually one workflow contains one process.	Yes
name	Unique state name. Use descriptive names such as Verification or Collection.	Yes
kind	Always StateConfig.	Yes
init_state	Marks the starting state.	Starting state only
final_state	Marks a state where the conversation can end.	Optional
description	The instructions the agent follows in this state: steps, guidelines, and example dialogues.	Yes
available_tools	The tools the agent can use in this state.	Yes

warning

A workflow must contain exactly one state with init_state: true. For text agents, include SendChatMessage in available_tools — without it the agent cannot send messages to customers.

A good description has three parts: numbered steps to follow, important guidelines (including limitations), and example dialogues for both successful and problematic turns. Avoid conflicting instructions, and give each state one clear goal.

Define transitions

Transitions in state_scenarios describe when the agent moves to another state:

state_scenarios:
  - next_state: Collection
    transition_name: verify_identity
    description: "Move to collection after confirming identity"

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

Field	What it does	Required
next_state	The state to move to. Must reference an existing state name.	Yes
transition_name	A name for the transition — it appears in trace logs and helps you debug the flow.	Yes
description	The condition that triggers this transition.	Yes
attached_tools	Additional tools available during the transition.	No
transition_observation	A note recorded about the outcome of the transition.	No

Make conditions distinct: if two transitions can apply in the same situation, the agent may pick the wrong one or loop between states. Include a fallback transition for unclear replies and an escalation path for customers who ask for a person.

Preview the workflow as a diagram

To check the structure visually:

1. In the Workflow section header, click Show diagram.
2. Select Simple for a compact diagram or Extended for a more detailed one.
3. The diagram opens in a window — drag to pan and scroll to zoom.
4. Click Export as SVG to download the diagram.

Test workflow changes

1. Click Save.
2. Restart the agent: Stop agent, wait for Stopped, then Start agent.
3. Open the Playground and walk through your scenarios: the main path, an off-topic question, and each transition.
4. If a transition misfires, open the session's trace logs from Sessions and search for the transition_name to see what the model received and decided.

Related pages

• Advanced mode overview — the full agent page and how to navigate it
• Prompts — the Identity, Speech style, and Task sections
• Knowledge and tools — attach the tools that states can use
• Playground — walk through workflow scenarios
• Sessions — review trace logs for transitions