Skip to main content

Best Practices

Start Simple and Iterate​

  • Begin with 1-2 states and add complexity only when needed
  • Test simple version thoroughly before adding states
  • Most use cases work well with minimal states

Example Evolution:

Original (6 states): ask_reason → ask_when → ask_how → confirm → schedule → close
Simplified (2 states): verification → collection

Result: Better performance, more natural conversations, easier maintenance

Clear State Purpose​

  • Each state should have one clear goal
  • Avoid states that try to do too many things
  • Use descriptive state names

Good vs Poor State Design:

✅ Good State Design:
- Verification: Confirm identity before proceeding
- Collection: Handle payment discussion and arrangement
- Escalation: Transfer to human operator

❌ Poor State Design:
- State1: Do various things depending on situation
- ProcessingState: Handle multiple different processes

Comprehensive Examples​

  • Provide dialogue examples for main scenarios
  • Examples strongly influence agent behavior
  • Include both successful and problematic interactions

Explicit Transitions​

  • Make transition conditions clear and unambiguous
  • Avoid overlapping transition conditions
  • Test all possible transition paths

Clear vs Problematic Conditions:

❌ Problematic:
- verify_identity: "When identity is confirmed"
- proceed_to_collection: "When ready to discuss payment"

✅ Clear:
- verify_identity: "When customer confirms they are the correct person"
- end_wrong_person: "When customer says they are not the target person"

Error Handling and Fallbacks​

  • Always include paths for unexpected responses
  • Plan for edge cases and user confusion
  • Have fallback states for error conditions

Always Include Fallback Paths:

state_scenarios:
  - next_state: MainFlow
    transition_name: normal_progression
    description: "Standard flow continuation"
  
  - next_state: Clarification
    transition_name: handle_confusion
    description: "When user response is unclear or unexpected"
  
  - next_state: Escalation
    transition_name: request_human
    description: "When user explicitly requests human agent"

Plan for User Confusion:

description: |
  If the user's response is unclear or doesn't match expected answers:
  1. Politely ask for clarification
  2. Provide examples of expected responses
  3. If still unclear after 2 attempts, escalate to human operator

Use Templates​

  • Leverage template library when available
  • Don't build complex workflows from scratch
  • Adapt existing templates to your use case