​
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:

  1. Accepts a user message as input.
  2. Searches Google and Wikipedia for relevant context.
  3. Processes search results and appends them to the conversation history.
  4. Generates a final LLM response.
  5. 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.
LoopsConditions and Branches