​
What Are Steps?

Steps = Focused Responsibilities

Each step has a single, well-defined purpose in your agent’s workflow. This decomposition makes complex agent behavior manageable and predictable.

Single Purpose

Each step handles one specific type of interaction or task

Controlled Tools

Steps only have access to tools they actually need

Clear Transitions

Explicit conditions determine when and where to move next

Independent Testing

Each step can be tested and validated separately

​
Step Anatomy

​
Basic Step Structure

steps:
  - step_id: greet_customer
    description: |
      Welcome the customer and understand their needs.
      Ask how you can help them today and listen for their response.
    available_tools: []
    routes:
      - target: take_order
        condition: Customer wants to place an order
      - target: customer_support
        condition: Customer has questions or needs help
      - target: end
        condition: Customer wants to leave
    examples:
      - context: "New customer enters"
        decision: "Greet warmly and ask how to help"
        visibility: "always"

​
Step Components

Step ID: Unique identifier for the step

step_id: take_coffee_order

This is how other steps reference this step in their routes.

​
Advanced Step Features

​
Step Examples

Provide examples to help the LLM understand expected behavior:

- step_id: handle_complaint
  description: |
    Listen to customer complaints with empathy and work toward resolution.
  available_tools:
    - lookup_order_history
    - check_return_policy
    - issue_refund
  examples:
    - context: "Customer received damaged item"
      decision: "Apologize, lookup order, offer refund or replacement"
      visibility: "always"
    - context: "Customer angry about delivery delay"
      decision: "Acknowledge frustration, investigate delay, offer compensation"
      visibility: "when_relevant"

​
Conditional Tool Access

Tools can be conditionally available based on context:

- step_id: manager_escalation
  description: |
    Handle escalated issues that require manager authority.
  available_tools:
    - basic_customer_lookup
    - issue_special_discount  # Only available in this step
    - override_policy        # Manager-level tool
    - escalate_to_regional   # Final escalation option
  routes:
    - target: resolution_complete
      condition: Issue resolved with manager intervention
    - target: regional_escalation
      condition: Issue requires regional manager

​
Step Transitions and Routing

​
Route Conditions

Route conditions should be clear and specific:

routes:
  # Good: Specific conditions
  - target: payment_processing
    condition: Customer provided valid payment method and confirmed order total

  # Good: Business logic conditions
  - target: manager_approval
    condition: Order total exceeds $1000 and requires manager approval

  # Good: Error handling
  - target: retry_payment
    condition: Payment failed due to insufficient funds

  # Avoid: Vague conditions
  # - target: next_step
  #   condition: When ready

​
Complex Routing Logic

Handle multiple routing scenarios:

- step_id: order_validation
  description: |
    Validate order details and route based on validation results.
  available_tools:
    - validate_shipping_address
    - check_inventory_availability
    - verify_payment_method
  routes:
    - target: process_order
      condition: All validations pass and order can be processed immediately
    - target: address_correction
      condition: Shipping address needs correction
    - target: inventory_backorder
      condition: Some items are backordered but customer accepts delay
    - target: payment_issues
      condition: Payment method validation failed
    - target: order_cancellation
      condition: Critical validation failures that cannot be resolved

​
Error Handling in Steps

​
Graceful Error Recovery (Coming Soon)

- step_id: external_api_integration
  description: |
    Integrate with external service, handling potential failures gracefully.
  available_tools:
    - call_external_api
    - fallback_local_data
    - notify_technical_team
  routes:
    - target: api_success_processing
      condition: External API call successful
    - target: fallback_processing
      condition: API unavailable but fallback data sufficient
    - target: service_unavailable
      condition: Neither API nor fallback available
  error_handling:
    max_retries: 3
    timeout: 30
    fallback_step: service_unavailable

​
Step Performance and Optimization

​
Efficient Tool Usage

- step_id: optimized_lookup
  description: |
    Efficiently lookup customer information using cached data when possible.
  available_tools:
    - quick_customer_lookup   # Fast, cached lookup
    - detailed_customer_fetch # Slower, comprehensive lookup
    - update_customer_cache   # Update cache with new info
  routes:
    - target: serve_from_cache
      condition: Customer info found in cache and is recent
    - target: fetch_and_cache
      condition: Customer info not cached or outdated

​
Testing Individual Steps

Steps can be tested independently:

# tests.agent.yaml
unit:
  test_greeting_step:
    context:
      current_step_id: "greeting"
    input: "Hello, I'm looking for help with my order"
    expectation: "Greets customer and routes to support_request step"

  test_order_step_with_tools:
    context:
      current_step_id: "take_order"
    input: "I'd like a large latte with oat milk"
    expectation: "Uses menu tools and adds specific item to cart"

  test_error_handling:
    context:
      current_step_id: "payment_processing"
    input: "My card was declined"
    expectation: "Provides helpful error message and routes to payment_retry"

​
Best Practices for Step Design

​
1. Single Responsibility Principle

One Job Per Step

Each step should have one clear purpose

# Good: Focused steps
- step_id: collect_shipping_address
- step_id: validate_shipping_address
- step_id: calculate_shipping_cost

# Avoid: Overloaded steps
# - step_id: handle_all_shipping_stuff

​
2. Clear Transition Logic

Explicit Routing

Make transition conditions obvious and testable

routes:
  # Good: Clear conditions
  - target: payment_success
    condition: Payment processed successfully and confirmation email sent

  # Avoid: Ambiguous conditions
  # - target: next
  #   condition: When done

​
3. Appropriate Tool Access

Minimal Tool Scope

Only provide tools that are needed for the step’s purpose

- step_id: customer_greeting
  available_tools: []  # No tools needed for greeting

- step_id: lookup_order
  available_tools:
    - search_orders    # Only order search capability

- step_id: process_refund
  available_tools:
    - search_orders    # Need to find order
    - issue_refund     # Need to process refund
    # No other payment tools

​
4. Comprehensive Error Handling

Expect the Unexpected

Plan for failure scenarios and edge cases

- step_id: api_dependent_step
  routes:
    - target: success_path
      condition: API call successful
    - target: retry_path
      condition: API call failed but retryable
    - target: fallback_path
      condition: API unavailable but alternative exists
    - target: failure_path
      condition: No alternatives available

Start Simple, Then Refine

Begin with basic steps and gradually add complexity. It’s easier to split a step that’s doing too much than to combine steps that are too granular.

​
Real-World Step Examples

Here are well-designed steps from the NOMOS examples:

- step_id: start
  description: |
    Greet the customer and ask how can I help them.
    Use the get_available_coffee_options tool if they need menu information.
  available_tools:
    - get_available_coffee_options
  routes:
    - target: take_coffee_order
      condition: Customer is ready to place a new order

- step_id: take_coffee_order
  description: |
    Ask for coffee preference and size.
    Manage cart operations based on customer requests.
  available_tools:
    - get_available_coffee_options
    - add_to_cart
    - remove_item
    - clear_cart
  routes:
    - target: finalize_order
      condition: User wants to finalize the order
    - target: end
      condition: Customer wants to cancel

Steps are the foundation of reliable AI agents. By designing them with clear purposes, appropriate tool access, and explicit transition logic, you create agents that are both powerful and predictable.