> ## Documentation Index
> Fetch the complete documentation index at: https://docs.gp.scale.com/llms.txt
> Use this file to discover all available pages before exploring further.

# State Machines

> Combining multiple workflows to solve tasks.

## **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**

```yaml theme={null}
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
```

<img height="1608" width="2048" src="https://lh7-rt.googleusercontent.com/docsz/AD_4nXcGg2E0v3LNVHmeljy8idKPB1YgWNpwcLa0j9jsquHtW62O81S1nPC1LhsRlcvZvud73kkn-aTCCTuOP8G8ZHd2eJ357hNyPuC6Mv2ePem9r_kMeJlJgIEdziya09ZwMVcRuxFGYw?key=4UQ2rxZFcFiohhkK9_YjC7dy" />

## Breaking Down the State Machine Implementation

### 1. Initial State Configuration

The `initial_state` defines **default system messages** stored across interactions.

```yaml theme={null}
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:

```yaml theme={null}
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**:

```yaml theme={null}
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.