Skip to content

AutoGPT is the vision of accessible AI for everyone, to use and to build on. Our mission is to provide the tools, so that you can focus on what matters.

fix(copilot): Clarify StoreValueBlock vs PersistInformationBlock (#13445)

Toran Bruce Richardsd023de5ce494
diff --git a/autogpt_platform/backend/backend/blocks/basic.py b/autogpt_platform/backend/backend/blocks/basic.py
index 0148f84bc0..f71eb1e589 100644
--- a/autogpt_platform/backend/backend/blocks/basic.py
+++ b/autogpt_platform/backend/backend/blocks/basic.py
@@ -1,4 +1,5 @@
import enum
+import inspect
from typing import Any
from backend.blocks._base import (
@@ -68,9 +69,12 @@ class FileStoreBlock(Block):
class StoreValueBlock(Block):
"""
- This block allows you to provide a constant value as a block, in a stateless manner.
- The common use-case is simply pass the `input` data, it will `output` the same data.
- The block output will be static, the output can be consumed multiple times.
+ Holds or receives a value and outputs it statically so that it can be used multiple
+ times within the same agent run. Whenever consumed, the output value reflects the
+ last input value that was received.
+
+ NOTE: The value is NOT persisted across runs. To store data that survives between
+ runs, use PersistInformationBlock and RetrieveInformationBlock instead.
"""
class Input(BlockSchemaInput):
@@ -90,7 +94,7 @@ class StoreValueBlock(Block):
def __init__(self):
super().__init__(
id="1ff065e9-88e8-4358-9d82-8dc91f622ba9",
- description="A basic block that stores and forwards a value throughout workflows, allowing it to be reused without changes across multiple blocks.",
+ description=inspect.cleandoc(StoreValueBlock.__doc__ or ""),
categories={BlockCategory.BASIC},
input_schema=StoreValueBlock.Input,
output_schema=StoreValueBlock.Output,
diff --git a/autogpt_platform/backend/backend/blocks/persistence.py b/autogpt_platform/backend/backend/blocks/persistence.py
index 7584993beb..4858ea2cda 100644
--- a/autogpt_platform/backend/backend/blocks/persistence.py
+++ b/autogpt_platform/backend/backend/blocks/persistence.py
@@ -1,3 +1,4 @@
+import inspect
import logging
from typing import Any, Literal
@@ -26,13 +27,23 @@ def get_storage_key(key: str, scope: StorageScope, graph_id: str) -> str:
class PersistInformationBlock(Block):
- """Block for persisting key-value data for the current user with configurable scope"""
+ """
+ Persists a key-value pair for use across multiple runs of an agent. Use this when
+ you need memory that persists between executions, e.g. last-seen state, counters,
+ accumulated data.
+
+ Beware of read->write race conditions for parallel use of the same key.
+ """
class Input(BlockSchemaInput):
key: str = SchemaField(description="Key to store the information under")
value: Any = SchemaField(description="Value to store")
scope: StorageScope = SchemaField(
- description="Scope of persistence: within_agent (shared across all runs of this agent) or across_agents (shared across all agents for this user)",
+ description=(
+ "Scope of persistence: "
+ "'within_agent' — shared across all runs of this agent; "
+ "'across_agents' — shared across all agents for this user"
+ ),
default="within_agent",
)
@@ -42,7 +53,7 @@ class PersistInformationBlock(Block):
def __init__(self):
super().__init__(
id="1d055e55-a2b9-4547-8311-907d05b0304d",
- description="Persist key-value information for the current user",
+ description=inspect.cleandoc(PersistInformationBlock.__doc__ or ""),
categories={BlockCategory.DATA},
input_schema=PersistInformationBlock.Input,
output_schema=PersistInformationBlock.Output,
@@ -94,12 +105,16 @@ class PersistInformationBlock(Block):
class RetrieveInformationBlock(Block):
- """Block for retrieving key-value data for the current user with configurable scope"""
+ """Reads back a key-value pair previously saved by PersistInformationBlock."""
class Input(BlockSchemaInput):
key: str = SchemaField(description="Key to retrieve the information for")
scope: StorageScope = SchemaField(
- description="Scope of persistence: within_agent (shared across all runs of this agent) or across_agents (shared across all agents for this user)",
+ description=(
+ "Scope of persistence: "
+ "'within_agent' — shared across all runs of this agent; "
+ "'across_agents' — shared across all agents for this user"
+ ),
default="within_agent",
)
default_value: Any = SchemaField(
@@ -112,7 +127,7 @@ class RetrieveInformationBlock(Block):
def __init__(self):
super().__init__(
id="d8710fc9-6e29-481e-a7d5-165eb16f8471",
- description="Retrieve key-value information for the current user",
+ description=inspect.cleandoc(RetrieveInformationBlock.__doc__ or ""),
categories={BlockCategory.DATA},
input_schema=RetrieveInformationBlock.Input,
output_schema=RetrieveInformationBlock.Output,
diff --git a/autogpt_platform/backend/backend/copilot/sdk/agent_generation_guide.md b/autogpt_platform/backend/backend/copilot/sdk/agent_generation_guide.md
index 7eaa1d7140..cd94b12061 100644
--- a/autogpt_platform/backend/backend/copilot/sdk/agent_generation_guide.md
+++ b/autogpt_platform/backend/backend/copilot/sdk/agent_generation_guide.md
@@ -188,6 +188,15 @@ descriptions; read and follow those when `find_block` surfaces a match.
- **is_static links**: Set `is_static: true` when the link carries a
design-time constant (matches a field in inputSchema with a default).
- **ConditionBlock**: Needs a `StoreValueBlock` wired to its `value2` input.
+- **StoreValueBlock vs PersistInformationBlock** — these are NOT interchangeable:
+ - `StoreValueBlock` (ID: `1ff065e9-88e8-4358-9d82-8dc91f622ba9`) — holds a
+ constant **within one run only** (ephemeral). Use it to reuse a single output value
+ as input for multiple node runs (within the same agent run).
+ - `PersistInformationBlock` (ID: `1d055e55-a2b9-4547-8311-907d05b0304d`) +
+ `RetrieveInformationBlock` (ID: `d8710fc9-6e29-481e-a7d5-165eb16f8471`) —
+ write/read values that **survive across runs**. Use these whenever you need
+ memory, counters, last-seen state, or any data that must outlast a single
+ execution.
- **Prompt templates**: Use `{{variable}}` (double curly braces) for
literal braces in prompt strings — single `{` and `}` are for
template variables.
diff --git a/docs/integrations/README.md b/docs/integrations/README.md
index f0e5da3154..e8fd3f4397 100644
--- a/docs/integrations/README.md
+++ b/docs/integrations/README.md
@@ -85,7 +85,7 @@ Below is a comprehensive list of all available blocks, categorized by their prim
| [Slant3D Get Orders](block-integrations/slant3d/order.md#slant3d-get-orders) | Get all orders for the account |
| [Slant3D Slicer](block-integrations/slant3d/slicing.md#slant3d-slicer) | Slice a 3D model file and get pricing information |
| [Slant3D Tracking](block-integrations/slant3d/order.md#slant3d-tracking) | Track order status and shipping |
-| [Store Value](block-integrations/basic.md#store-value) | A basic block that stores and forwards a value throughout workflows, allowing it to be reused without changes across multiple blocks |
+| [Store Value](block-integrations/basic.md#store-value) | Holds or receives a value and outputs it statically so that it can be used multiple times within the same agent run |
| [Universal Type Converter](block-integrations/basic.md#universal-type-converter) | This block is used to convert a value to a universal type |
| [XML Parser](block-integrations/basic.md#xml-parser) | Parses XML using gravitasml to tokenize and coverts it to dict |
| [Zip Lists](block-integrations/basic.md#zip-lists) | Zips multiple lists together into a list of grouped elements |
@@ -179,10 +179,10 @@ Below is a comprehensive list of all available blocks, categorized by their prim
| [JSON Decoder](block-integrations/data.md#json-decoder) | Decodes a JSON string into the value or data structure, it represents, e |
| [JSON Encoder](block-integrations/data.md#json-encoder) | Encodes any value or data structure into a JSON string |
| [Keyword Suggestion Extractor](block-integrations/dataforseo/keyword_suggestions.md#keyword-suggestion-extractor) | Extract individual fields from a KeywordSuggestion object |
-| [Persist Information](block-integrations/data.md#persist-information) | Persist key-value information for the current user |
+| [Persist Information](block-integrations/data.md#persist-information) | Persists a key-value pair for use across multiple runs of an agent |
| [Read Spreadsheet](block-integrations/data.md#read-spreadsheet) | Reads CSV and Excel files and outputs the data as a list of dictionaries and individual rows |
| [Related Keyword Extractor](block-integrations/dataforseo/related_keywords.md#related-keyword-extractor) | Extract individual fields from a RelatedKeyword object |
-| [Retrieve Information](block-integrations/data.md#retrieve-information) | Retrieve key-value information for the current user |
+| [Retrieve Information](block-integrations/data.md#retrieve-information) | Reads back a key-value pair previously saved by PersistInformationBlock |
| [SQL Query](block-integrations/data.md#sql-query) | Execute a SQL query |
| [Screenshot Web Page](block-integrations/data.md#screenshot-web-page) | Takes a screenshot of a specified website using ScreenshotOne API |
diff --git a/docs/integrations/block-integrations/basic.md b/docs/integrations/block-integrations/basic.md
index b8cd1ce18b..5c4f10fbce 100644
--- a/docs/integrations/block-integrations/basic.md
+++ b/docs/integrations/block-integrations/basic.md
@@ -1496,7 +1496,12 @@ The search is performed against the Mem0 memory store and returns memories ranke
## Store Value
### What it is
-A basic block that stores and forwards a value throughout workflows, allowing it to be reused without changes across multiple blocks.
+Holds or receives a value and outputs it statically so that it can be used multiple
+times within the same agent run. Whenever consumed, the output value reflects the
+last input value that was received.
+
+NOTE: The value is NOT persisted across runs. To store data that survives between
+runs, use PersistInformationBlock and RetrieveInformationBlock instead.
### How it works
<!-- MANUAL: how_it_works -->
diff --git a/docs/integrations/block-integrations/data.md b/docs/integrations/block-integrations/data.md
index 67416d5280..cf3bd2c24c 100644
--- a/docs/integrations/block-integrations/data.md
+++ b/docs/integrations/block-integrations/data.md
@@ -193,7 +193,11 @@ Before outputting, the block validates JSON-serializability. If an unsupported t
## Persist Information
### What it is
-Persist key-value information for the current user
+Persists a key-value pair for use across multiple runs of an agent. Use this when
+you need memory that persists between executions, e.g. last-seen state, counters,
+accumulated data.
+
+Beware of read->write race conditions for parallel use of the same key.
### How it works
<!-- MANUAL: how_it_works -->
@@ -208,7 +212,7 @@ The stored data remains available until explicitly overwritten, enabling state m
|-------|-------------|------|----------|
| key | Key to store the information under | str | Yes |
| value | Value to store | Value | Yes |
-| scope | Scope of persistence: within_agent (shared across all runs of this agent) or across_agents (shared across all agents for this user) | "within_agent" \| "across_agents" | No |
+| scope | Scope of persistence: 'within_agent' — shared across all runs of this agent; 'across_agents' — shared across all agents for this user | "within_agent" \| "across_agents" | No |
### Outputs
@@ -277,7 +281,7 @@ Configure delimiter, quote character, and escape character for proper CSV parsin
## Retrieve Information
### What it is
-Retrieve key-value information for the current user
+Reads back a key-value pair previously saved by PersistInformationBlock.
### How it works
<!-- MANUAL: how_it_works -->
@@ -291,7 +295,7 @@ Use within_agent scope for agent-specific data or across_agents for data shared
| Input | Description | Type | Required |
|-------|-------------|------|----------|
| key | Key to retrieve the information for | str | Yes |
-| scope | Scope of persistence: within_agent (shared across all runs of this agent) or across_agents (shared across all agents for this user) | "within_agent" \| "across_agents" | No |
+| scope | Scope of persistence: 'within_agent' — shared across all runs of this agent; 'across_agents' — shared across all agents for this user | "within_agent" \| "across_agents" | No |
| default_value | Default value to return if key is not found | Default Value | No |
### Outputs