State Machines

Overview

A State Machine in Agent Service enables structured, stateful workflows that transition between different states based on workflow outcomes. Unlike simple sequential workflows, a State Machine supports branching, conditional paths, and user-driven transitions, making it ideal for interactive AI applications. This guide explains how to implement a State Machine using an AI-powered search chat agent as an example. The agent integrates Google Search and Wikipedia Search to answer user queries dynamically.

What is a State Machine?

A State Machine consists of:

States (Workflows): Individual processing units that transform input data.
State Transitions: Rules that determine the next state based on workflow outputs.
Persistent State Management: The system retains and updates messages across states, enabling multi-turn interactions.

Example: Search Chat State Machine

The following YAML configures a State Machine that:

Accepts a user message as input.
Searches Google and Wikipedia for relevant context.
Processes search results and appends them to the conversation history.
Generates a final LLM response.
Loops back to continue the conversation.

Note that this example uses two pre-built internal tools for Google Search and Wikipedia Search.

YAML Configuration

account_id: 66049ada2fc77c99ef015be7

initial_state:
  messages:
    - role: system
      content: "Answer using Google and Wikipedia as needed."

starting_node: search_chat

machine:
  search_chat:  
    workflow_config:
      final_output_nodes: ["llm_call"]
      user_input:
        message:
          type: string
      workflow:
        - name: get_new_user_message
          type: create_messages
          config:
            message_configs:
              - role: user
                content: user_message
          inputs:
            user_message: message

        - name: add_user_message
          type: insert_messages
          config:
            index: -1
          inputs:
            messages: messages
            new_messages: get_new_user_message.output

        - name: search_generation
          type: tool_generation
          config:
            model: openai/gpt-4o
            tools:
              - name: internal.google_search
              - name: internal.WikipediaSearch
                init_kwargs: {}
          inputs:
            messages: add_user_message.output

        - name: add_tool_and_asst_msgs
          type: processor
          config:
            return_key: concatenate
            function_specs:
              concatenate:
                path: concatenate
                kwargs:
                  list1: list1
                  list2: list2
          inputs:
            list1: add_user_message.output
            list2: search_generation.output
        
        - name: llm_call
          type: get_message
          config:
            index: -1
          inputs:
            messages: add_tool_and_asst_msgs.output

    write_to_state:
      messages: add_tool_and_asst_msgs
    
    next_node:
      default: search_chat

Breaking Down the State Machine Implementation

1. Initial State Configuration

The initial_state defines default system messages stored across interactions.

initial_state:
  messages:
    - role: system
      content: "Answer using Google and Wikipedia as needed."

2. Defining the State (Workflow)

The search_chat state processes user queries, retrieves relevant information, and generates responses. User Message Handling

get_new_user_message: Formats user input as a message.
add_user_message: Inserts the new message into conversation history. Retrieving Search Results
search_generation: Calls Google Search and Wikipedia to fetch relevant information. Processing Results
add_tool_and_asst_msgs: Merges retrieved search results with prior conversation history. Generating Final Response
llm_call: Extracts the latest message from the updated conversation.

3. Writing to State

Each state persists conversation history updates to ensure multi-turn responses:

write_to_state:
  messages: add_tool_and_asst_msgs

4. Transitioning to the Next State

The system loops back to search_chat, enabling continuous interaction:

next_node:
  default: search_chat

Why Use a State Machine?

Dynamic Control Flow: Workflows adapt based on AI-generated content.
Persistent Context: Stores conversation history for multi-turn interactions.
Seamless API Integration: Supports external tools like Google Search and Wikipedia.
Scalable: Can be extended to include multiple states and advanced branching. This example showcases a responsive, knowledge-powered AI assistant built using a State Machine, making it ideal for chatbots, automated research assistants, and context-aware AI agents.

Getting Started

Infrastructure

Agents

Evaluations

Uploading Data

Creating Applications

Creating Applications

Evaluation Datasets

Inference

Miscellaneous

Managing Annotations

Components

Overview

What is a State Machine?

Example: Search Chat State Machine

YAML Configuration

Breaking Down the State Machine Implementation

1. Initial State Configuration

2. Defining the State (Workflow)

3. Writing to State

4. Transitioning to the Next State

Why Use a State Machine?

​Overview

​What is a State Machine?

​Example: Search Chat State Machine

​YAML Configuration

​Breaking Down the State Machine Implementation

​1. Initial State Configuration

​2. Defining the State (Workflow)

​3. Writing to State

​4. Transitioning to the Next State

​Why Use a State Machine?

Overview

What is a State Machine?

Example: Search Chat State Machine

YAML Configuration

Breaking Down the State Machine Implementation

1. Initial State Configuration

2. Defining the State (Workflow)

3. Writing to State

4. Transitioning to the Next State

Why Use a State Machine?