Skip to main content

Core Configuration Fields

1. Process and State Identification​

- process_name: MyWorkflow        # Groups related states together
  name: InitialState             # Unique state identifier
  kind: StateConfig              # Always "StateConfig"
  init_state: true              # Marks the starting state (only one per workflow)
  final_state: true             # Marks ending states (can have multiple)

2. State Description​

The description field contains detailed instructions for the agent. Use the pipe character (|) to write multiple lines:

description: |
  ## Steps to follow
    1. First, do this specific action
    2. Then, check for these conditions
    3. Route to appropriate next state
  
  ## Important Guidelines
    - Always be polite and professional
    - Use knowledge base for answering questions
    - Don't make assumptions about user intent
  
  ## Example dialogues
    ### Scenario 1
      Agent: Hello! How can I help you today?
      Human: I need help with my application
      Agent: <Action: provide_assistance>

Best Practices for Descriptions:

  • Use clear, step-by-step instructions
  • Include important guidelines and constraints
  • Provide dialogue examples for main scenarios
  • Be specific about expected behaviors

3. Available Tools​

Define which actions the agent can perform in each state:

available_tools:
  SingleStatefulOutboundAgent:  # The agent type (from your configuration)
    - SendChatMessage          # Send a message to the user
    - SingleSearchFAQ          # Search the knowledge base
    - CreateJiraTicket         # Create a support ticket

Common Tool Types​

ToolWhat it does
SendChatMessageSends a message to the user
SuggestChatMessageSuggests a message (for human operators)
FinishSessionEnds the conversation
SingleSearchFAQSearch the knowledge base
SchedulePaymentSchedule payment arrangements
TransferToOperatorTransfer to human operator

Tool Categories​

  • Communication: SendChatMessage, FinishSession
  • Knowledge: SingleSearchFAQ, SearchDatabase
  • External Actions: CreateJiraTicket, SendEmail, SchedulePayment
  • Custom Tools: From Skill Groups (varies by configuration)

4. State Transitions​

Define how and when to move between states:

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 user is busy"

Transition Fields Explained​

FieldWhat it doesExampleRequired
next_stateThe state to move toCollectingInformationYes
transition_nameA name for this transitionCustomerGreetedYes
descriptionWhen to make this transition"Move to information collection..."Yes
attached_toolsAdditional tools available during transition[SendVerificationTemplate]No

Advanced Workflow Features​

Skills Initialization and Finalization​

init_skills:
  UpdateOutcomeStatusSkill:
    new_outcome_status: "COLLECTION_STARTED"
  LoadCustomerDataSkill:
    customer_id: "12345"

final_skills:
  SendConfirmationEmail: {}

Purpose:

  • init_skills: Execute actions when entering a state (for example, load customer data)
  • final_skills: Execute actions when leaving a state (less commonly used)

⚠️ Important: Skills can be parameterized with specific values for different states.

Prompt Overrides​

Customize the agent's behavior for specific states:

prompt_fields_override:
  speech_style_extra: |
    Be extra empathetic in this state.
    Use softer language and show understanding.
  identity_override: |
    You are now in "good cop" mode. Be understanding and helpful.

Use Case: Change agent personality for specific situations (for example, switch from polite to more assertive after multiple failed attempts).

Process Dependencies​

enable_at: "MainProcess.VerificationComplete"

Purpose: Start dependent processes only after certain conditions are met. For example, an information-sharing process might only become available after customer verification.

Repeat Limits​

repeat_limit: 4
repeat_limit_next_state: "EscalationState"

Purpose: Automatically transition to another state after a certain number of attempts in the current state.

How State Transitions Work​

From User Perspective​

  1. Agent follows instructions in current state
  2. Based on user responses, agent takes actions
  3. Certain actions trigger automatic state transitions
  4. Agent behavior changes according to new state

Important Notes​

  • The agent doesn't "know" about states
  • Transitions like verify_identity appear as normal actions to the agent
  • The platform handles actual state changes behind the scenes
  • State changes are transparent to end users

Choosing the Right Number of States​

Key Principle​

Balance between control and intelligence

Pros:

  • More intelligent, flexible agent behavior
  • Can handle unexpected responses naturally
  • Easier to maintain and debug

Cons:

  • Less predictable behavior
  • Requires more sophisticated prompting

More States​

Pros:

  • Strict control over conversation flow
  • Predictable behavior
  • Clear audit trail

Cons:

  • Can become script-like
  • Difficult to handle unexpected responses
  • Complex configuration and maintenance

Example Evolution​

A collection workflow initially had 6 states (ask reason → ask when → ask how → confirm), but was simplified to 2 states (verification → collection) for better performance. The single collection state now handles all payment discussion naturally.

Testing and Debugging Workflows​

Testing Strategy​

  1. Unit Test States: Test each state individually
  2. Integration Test: Test complete workflow paths
  3. Edge Case Testing: Test unexpected user responses
  4. Load Testing: Test with multiple concurrent conversations

Debugging Tools​

  • Playground: Test individual conversations
  • Session Logs: Analyze actual conversation flow
  • Prompt Logs: See exactly what the agent received and generated