Key-Value Storage

Stores data between sessions. Uses unique keys (names) to identify the data. Keys can only contain alphanumeric characters, underscores, and hyphens.

Overview

The Key-Value Storage block allows you to save data in the cloud between browser sessions and agent redeploys. Unlike agent state, which is session-based and temporary, Key-Value Storage provides persistent storage through browser refreshes, new sessions, and agent updates.

This block works with individual items or JSON-serializable objects such as lists, dictionaries, and other nested structures.

Storage scope: Key-Value Storage is per agent, not per user. All users of the same agent share the same storage namespace. If you need user-specific data, include a user identifier in your key names (for example, user_preferences_{user_id}) to ensure data isolation between users.

Common use cases

• Storing user preferences or settings that should persist across sessions
• Maintaining application data that needs to survive agent redeploys
• Storing configuration data or feature flags
• Persisting user progress or state in multi-step workflows

Key-value storage is not a secure way to store sensitive data. If you need to store sensitive data, use Vault.

How it works

The Key-Value Storage block provides four actions: save, get, delete, and list keys.

Save

Specify a key (name) and a value you want to associate with it. If this key already exists, the existing value is updated. If it doesn’t exist, it is created.

• Key: A unique identifier for your data. Keys can only contain alphanumeric characters, underscores, and hyphens.
• Value type: Choose how to interpret the value:
  • Plain text: Stores the value as a string.
  • JSON: Parses the value as JSON, allowing you to store objects, lists, and nested structures directly.
• Value: The data you want to store. You can enter plain text, use expressions like @{state.username}, or enter JSON directly when using JSON value type.

When you save a value, it’s stored in the cloud and associated with your agent. The data persists even if the user closes their browser or you redeploy the agent.

To store structured data (objects, lists, nested structures), set Value type to JSON and enter your data directly in the Value field, or reference a state variable using @{state.variable_name}.

Get

Specify a key name to retrieve the data you’ve stored under that key. If the key exists, the block returns the stored value. If the key doesn’t exist, the block raises an error that you can handle with error routing.

The retrieved value maintains its original structure. If you stored a complex object as JSON, you’ll get back the same structure with all nested attributes accessible.

Delete

Specify a key name to delete the data associated with that key. This permanently removes the key-value pair from storage. If you try to delete a key that doesn’t exist, the block raises an error.

List keys

Retrieve a list of all keys currently stored for your agent. This action doesn’t require a key parameter, and returns an array of key names that you can use to iterate over stored data or check what data exists.

Accessing nested data

When you store structured data (either by setting Value type to JSON or by referencing a state variable like @{state.user_profile}), you can access nested attributes directly in subsequent blocks using dot notation, similar to how you access nested state variables.

For example, if state.user_profile contains:

{
  "name": "John Doe",
  "preferences": {
    "theme": "dark",
    "language": "en"
  },
  "tasks": [
    {"id": 1, "title": "Task 1"},
    {"id": 2, "title": "Task 2"}
  ]
}

After saving this data (either by entering the JSON directly with Value type set to JSON, or by using @{state.user_profile} as the Value), you can retrieve it with the Get action and access nested values in subsequent blocks using dot notation:

• @{result.name} returns “John Doe”
• @{result.preferences.theme} returns “dark”
• @{result.tasks.0.title} returns “Task 1”

Examples

Caching computed results

This example shows how to cache expensive computations for reuse.

Blueprint Flow:

1. UI Trigger → User requests data analysis
2. Key-Value Storage (Get) → Attempts to retrieve cached result with key analysis_result
   • Success path → Display cached result
   • Error path → If cache doesn’t exist:
     • Python code → Perform expensive computation
     • Key-Value Storage (Save) → Store result with key analysis_result
     • Set state → Display result to user

Managing application configuration

This example demonstrates storing configuration data that survives agent redeploys.

Blueprint Flow:

1. UI Trigger → Admin updates configuration
2. Key-Value Storage (Save) → Stores configuration with key app_config
3. Set state → Confirms update

In other parts of the agent:

1. Key-Value Storage (Get) → Retrieves configuration with key app_config
2. Python code → Uses configuration values (accessible via @{result}) to control agent behavior

Fields

Name	Type	Control	Default	Description	Options	Validation
Action	Text	-	Save	-	Save - Save Get - Get Delete - Delete List keys - List keys	-
Key	Text	-	-	-	-	-
Value type	Text	-	text	-	text - Plain text JSON - JSON	-
Value	Text	Textarea	-	-	-	-

End states

Below are the possible end states of the block call.

Name	Field	Type	Description
Success	-	success	The request was successful.
Error	-	error	The request wasn’t successful.