Agentuity Docs

When to Use Key-Value Storage

Key-value storage is your go-to solution for fast, ephemeral data that agents need to access quickly. Think of it as your agent's short-term memory — perfect for session state, configuration, caching, and temporary data.

Choose the right storage for your use case:

Key-Value: Fast lookups, simple data, temporary state
Vector Storage: Semantic search, embeddings, similarity matching
Object Storage: Large files, media, backups

Common Use Cases

Session Management: Store user sessions, authentication tokens, and temporary state between agent interactions
Configuration Storage: Keep agent-specific settings, feature flags, and runtime configuration that can be updated without redeployment
Caching: Cache expensive computation results, API responses, or frequently accessed data to improve agent performance
Inter-Agent Communication: Share state between agents working together on complex workflows
Rate Limiting: Track API usage, request counts, and implement throttling mechanisms

Creating Key-Value Storage

You can create key-value storage either through the Cloud Console or programmatically in your agent code.

Via Cloud Console

Navigate to Services > Key Value and click Create Storage. Choose a descriptive name that reflects the storage purpose (e.g., user-sessions, agent-config, api-cache).

Via SDK

Both JavaScript and Python SDKs automatically create key-value storage when you first access it:

// JavaScript/TypeScript
import { AgentHandler } from '@agentuity/sdk';

const handler: AgentHandler = async (req, resp, ctx) => {
// Buckets are auto-created if they don't exist
await ctx.kv.set('user-sessions', 'user-123', {
  lastSeen: new Date().toISOString(),
  preferences: { theme: 'dark' }
});

return resp.json({ message: 'Session stored' });
};

export default handler;

# Python
from agentuity import AgentRequest, AgentResponse, AgentContext
from datetime import datetime

async def run(request: AgentRequest, response: AgentResponse, context: AgentContext):
  # Storage is created automatically on first use
  await context.kv.set("user-sessions", "user-123", {
      "lastSeen": datetime.now().isoformat(),
      "preferences": {"theme": "dark"}
  })
  
  return response.json({"message": "Session stored"})

Working with Key-Value Storage

The key-value API provides three core operations: get, set, and delete. All operations are asynchronous and support various data types.

The first parameter in all operations is the storage bucket name (also called "name" or "namespace"). Buckets are automatically created when you first use them.

Storing Data

Store strings, objects, or binary data. Keys persist indefinitely by default, or you can set a TTL (time-to-live) for automatic expiration:

// Simple store
await ctx.kv.set('cache', 'api-response', responseData);

// Store an object
await ctx.kv.set('user-prefs', userId, {
language: 'en',
timezone: 'UTC'
});

// Store with TTL (expires after 1 hour)
await ctx.kv.set('sessions', sessionId, userData, { 
ttl: 3600,  // seconds
contentType: 'application/json'
});

// Store feature flags (no TTL - persistent config)
await ctx.kv.set('feature-flags', 'beta-features', {
darkMode: true,
aiAssistant: false,
newDashboard: true
});

# Simple store
await context.kv.set("cache", "api-response", response_data)

# Store an object
await context.kv.set("user-prefs", user_id, {
  "language": "en",
  "timezone": "UTC"
})

# Store with TTL (expires after 1 hour)
await context.kv.set("sessions", session_id, user_data, {
  "ttl": 3600  # seconds
})

# Store feature flags (no TTL - persistent config)
await context.kv.set("feature-flags", "beta-features", {
  "darkMode": True,
  "aiAssistant": False,
  "newDashboard": True
})

Retrieving Data

Retrieve stored values with automatic deserialization:

// Get a value
const result = await ctx.kv.get('user-prefs', userId);

if (result.exists) {
// Access data using the Data interface
const preferences = await result.data.json();
console.log('User preferences:', preferences);
} else {
console.log('No preferences found for user');
}

// Handle missing keys gracefully
const configResult = await ctx.kv.get('config', 'app-settings');
const config = configResult.exists ? await configResult.data.json() : defaultConfig;

# Get a value
result = await context.kv.get("user-prefs", user_id)

if result.exists:
  # Access data using the Data interface
  preferences = await result.data.json()
  print(f"User preferences: {preferences}")
else:
  print("No preferences found for user")

# Handle missing keys gracefully
result = await context.kv.get("config", "app-settings")
config = await result.data.json() if result.exists else default_config

Deleting Data

Remove keys when they're no longer needed:

// Delete a single key
await ctx.kv.delete('sessions', sessionId);
console.log('Session deleted successfully');

# Delete a single key
await context.kv.delete("sessions", session_id)
print("Session deleted successfully")

Best Practices

Key Naming Conventions

Use hierarchical, descriptive keys to organize your data:

user:{userId}:preferences
session:{sessionId}:data
cache:api:{endpoint}:{params}

Error Handling

Always handle potential storage errors gracefully:

try {
const result = await ctx.kv.get('config', 'settings');
if (!result.exists) {
  // Initialize with defaults
  await ctx.kv.set('config', 'settings', defaultSettings);
}
} catch (error) {
ctx.logger.error('Storage error:', error);
// Fall back to in-memory defaults
}

try:
  result = await context.kv.get("config", "settings")
  if not result.exists:
      # Initialize with defaults
      await context.kv.set("config", "settings", default_settings)
except Exception as e:
  context.logger.error(f"Storage error: {e}")
  # Fall back to in-memory defaults

TTL Strategy

Keys persist indefinitely by default unless you specify a TTL (time-to-live) value. When you do specify a TTL, the minimum allowed value is 60 seconds.

Use TTL for temporary data to prevent storage bloat: