Setting Sessions

The Session Store API provides thread-scoped key-value storage for managing dynamic data across agent iterations. Session values persist throughout a conversation thread and can be used to store state, share data between agent calls, and attach additional content to user messages.

Overview

Session values are scoped to a specific thread ID and can include:

• Regular values: Key-value pairs for storing arbitrary data
• User parts: Special prefixed values (__user_part_*) that automatically attach to user messages
• Expiry: Optional expiration timestamps for temporary data

Basic Session Operations

JavaScript/TypeScript

import { Distri } from '@distri/core';

const client = new Distri({
  baseUrl: 'http://localhost:8787/api/v1',
});

const threadId = 'thread-123';

// Set a session value
await client.setSessionValue(
  threadId,
  'user_preference',
  { theme: 'dark', language: 'en' }
);

// Get a single session value
const value = await client.getSessionValue(threadId, 'user_preference');
console.log('User preference:', value);

// Get all session values
const allValues = await client.getSessionValues(threadId);
for (const [key, value] of Object.entries(allValues)) {
  console.log(`${key}:`, value);
}

// Delete a specific key
await client.deleteSessionValue(threadId, 'user_preference');

// Clear all values in a session
await client.clearSession(threadId);

Rust

use distri::Distri;
use serde_json::json;

#[tokio::main]
async fn main() -> Result<(), Box<dyn std::error::Error>> {
    let client = Distri::from_env();
    let session_id = "thread-123";

    // Set a session value
    client.set_session_value(
        session_id,
        "user_preference",
        json!({ "theme": "dark", "language": "en" }),
        None, // Optional expiry ISO timestamp
    ).await?;

    // Get a single session value
    let value = client.get_session_value(session_id, "user_preference").await?;
    println!("User preference: {:?}", value);

    // Get all session values as a HashMap
    let all_values = client.get_session_values(session_id).await?;
    for (key, value) in all_values {
        println!("{}: {:?}", key, value);
    }

    // Delete a specific key
    client.delete_session_value(session_id, "user_preference").await?;

    // Clear all values in a session
    client.clear_session(session_id).await?;

    Ok(())
}

API

# Set a session value
curl -X POST http://localhost:8787/api/v1/threads/thread-123/session \
  -H 'Content-Type: application/json' \
  -d '{
    "key": "user_preference",
    "value": {"theme": "dark", "language": "en"}
  }'

# Get a session value
curl http://localhost:8787/api/v1/threads/thread-123/session/user_preference

# Get all session values
curl http://localhost:8787/api/v1/threads/thread-123/session

# Delete a session value
curl -X DELETE http://localhost:8787/api/v1/threads/thread-123/session/user_preference

# Clear all session values
curl -X DELETE http://localhost:8787/api/v1/threads/thread-123/session

User Parts

User parts automatically attach to user messages when prefixed with __user_part_:

JavaScript/TypeScript

// Set a text user part
await client.setUserPartText(
  threadId,
  'screenshot_description',
  'Screenshot shows the login form with validation errors'
);

// Set an image user part
await client.setUserPartImage(
  threadId,
  'screenshot',
  {
    bytes: base64ImageString,
    mimeType: 'image/png',
    name: 'screenshot.png',
  }
);

// Delete a specific user part
await client.deleteUserPart(threadId, 'screenshot_description');

// Clear all user parts
await client.clearUserParts(threadId);

Rust

use distri::Distri;
use distri_types::Part;

let client = Distri::from_env();
let session_id = "thread-123";

// Set a text user part
client.set_user_part_text(
    session_id,
    "screenshot_description",
    "Screenshot shows the login form with validation errors",
).await?;

// Set an image user part
client.set_user_part_image(
    session_id,
    "screenshot",
    distri_types::FileType::Bytes {
        bytes: base64_image_string,
        mime_type: "image/png".to_string(),
        name: Some("screenshot.png".to_string()),
    },
).await?;

// Delete a specific user part
client.delete_user_part(session_id, "screenshot_description").await?;

// Clear all user parts
client.clear_user_parts(session_id).await?;

API

# Set a user part
curl -X POST http://localhost:8787/api/v1/threads/thread-123/session \
  -H 'Content-Type: application/json' \
  -d '{
    "key": "__user_part_screenshot",
    "value": {
      "part_type": "image_url",
      "image_url": {
        "url": "data:image/png;base64,..."
      }
    }
  }'

Session Value Expiry

Set expiration times for temporary data:

JavaScript/TypeScript

// Set a value with 24-hour expiry
const expiry = new Date();
expiry.setHours(expiry.getHours() + 24);

await client.setSessionValue(
  threadId,
  'temporary_data',
  { data: 'value' },
  expiry.toISOString()
);

Rust

use chrono::Utc;

let expiry = Utc::now() + chrono::Duration::hours(24);
client.set_session_value(
    session_id,
    "temporary_data",
    json!({ "data": "value" }),
    Some(&expiry.to_rfc3339()),
).await?;

API

curl -X POST http://localhost:8787/api/v1/threads/thread-123/session \
  -H 'Content-Type: application/json' \
  -d '{
    "key": "temporary_data",
    "value": {"data": "value"},
    "expires_at": "2024-12-31T23:59:59Z"
  }'

Use Cases

• Browser Automation: Store screenshots, DOM observations, and user interactions
• State Management: Maintain conversation context and user preferences
• Tool Integration: Share data between external tools and agent iterations
• Multi-step Workflows: Persist intermediate results across agent calls
• Rich User Input: Attach images, observations, and structured data to user messages