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

# Add to state list

Adds a new item to a list in the Agent's state. Useful for tracking multiple values over time.

<img src="https://mintcdn.com/writer/dHnl9w_Om9ycQRLE/images/agent-builder/blueprints/add-to-state-list-block.png?fit=max&auto=format&n=dHnl9w_Om9ycQRLE&q=85&s=100e5471f1ca96fe0db3e31f6032c060" alt="" width="2310" height="1490" data-path="images/agent-builder/blueprints/add-to-state-list-block.png" />

## Overview

This block adds a string value to a list in the agent's state. It behaves differently depending on the state element's type:

* If the state element doesn't already exist, the block creates it and adds the value to it.
* If the state element already exists as a list, the block adds the value to the list.
* If the state element exists but isn't a list, the block fails.

<Warning>The **Add to state list** block only accepts string values. If you pass a value such as a dictionary, it will be converted to a string and added to the list.</Warning>

## Example

The following example shows an **Add to state list** block as part of a **For-each** workflow.

<img src="https://mintcdn.com/writer/dHnl9w_Om9ycQRLE/images/agent-builder/blueprints/add-to-state-list-example.png?fit=max&auto=format&n=dHnl9w_Om9ycQRLE&q=85&s=d093788c9b4e0e578056caa75864838c" alt="" width="2852" height="1610" data-path="images/agent-builder/blueprints/add-to-state-list-example.png" />

The **For-each loop** block iterates over a list of values and generates text for each value. Then, the **Add to state list** block adds the result of each iteration to the state list called `text_gen_results`.

On the initial run, the **Add to state list** block creates the state element and adds the first value to it. Every subsequent run, the block adds the next value to the list.

## Fields

<table className="blueprintFields">
  <thead>
    <th>Name</th>
    <th>Type</th>
    <th>Control</th>
    <th>Default</th>
    <th>Description</th>
    <th>Options</th>
    <th>Validation</th>
  </thead>

  <tbody>
    <tr>
      <td>Link Variable</td>
      <td>Binding</td>
      <td>-</td>

      <td>
        <span>-</span>
      </td>

      <td>Set the variable here and use it across your agent.</td>

      <td>
        <span>-</span>
      </td>

      <td>
        <span>-</span>
      </td>
    </tr>

    <tr>
      <td>Value</td>
      <td>Text</td>
      <td>Textarea</td>

      <td>
        <span>-</span>
      </td>

      <td>-</td>

      <td>
        <span>-</span>
      </td>

      <td>
        <span>-</span>
      </td>
    </tr>
  </tbody>
</table>

## End states

Below are the possible end states of the block call.

<table className="blueprintFields">
  <thead>
    <th>Name</th>
    <th>Field</th>
    <th>Type</th>
    <th>Description</th>
  </thead>

  <tbody>
    <tr>
      <td>Success</td>
      <td>-</td>
      <td>success</td>
      <td>The item was added to the list.</td>
    </tr>

    <tr>
      <td>Error</td>
      <td>-</td>
      <td>error</td>
      <td>There was an error adding the item to the list.</td>
    </tr>
  </tbody>
</table>