Persistence

ERA Agent provides multiple levels of persistence for your code execution environment. Understanding how data persists is key to building reliable workflows.

What Persists?

In a persistent session, the following persist across code executions:

1. Variables & State

# First run
curl -X POST https://era-agent.yawnxyz.workers.dev/api/sessions/my-session/run \
  -H "Content-Type: application/json" \
  -d '{
    "code": "counter = 0\nuser_data = {\"name\": \"Alice\", \"score\": 0}"
  }'

# Later run - variables still exist
curl -X POST https://era-agent.yawnxyz.workers.dev/api/sessions/my-session/run \
  -H "Content-Type: application/json" \
  -d '{
    "code": "counter += 1\nuser_data[\"score\"] += 10\nprint(f\"Counter: {counter}, Score: {user_data[\"score\"]}\")"
  }'

2. Files

# Create file
curl -X POST https://era-agent.yawnxyz.workers.dev/api/sessions/my-session/run \
  -H "Content-Type: application/json" \
  -d '{
    "code": "with open(\"config.json\", \"w\") as f:\n    f.write(\"{\\\"setting\\\": \\\"value\\\"}\")"
  }'

# Read file in later run
curl -X POST https://era-agent.yawnxyz.workers.dev/api/sessions/my-session/run \
  -H "Content-Type: application/json" \
  -d '{
    "code": "with open(\"config.json\", \"r\") as f:\n    config = f.read()\nprint(f\"Config: {config}\")"
  }'

3. Imported Modules

# First run - import
curl -X POST https://era-agent.yawnxyz.workers.dev/api/sessions/my-session/run \
  -H "Content-Type: application/json" \
  -d '{
    "code": "import json\nimport math\nfrom datetime import datetime"
  }'

# Later run - imports still available
curl -X POST https://era-agent.yawnxyz.workers.dev/api/sessions/my-session/run \
  -H "Content-Type: application/json" \
  -d '{
    "code": "data = {\"timestamp\": datetime.now().isoformat()}\nprint(json.dumps(data))"
  }'

4. Session Metadata

# Create session with data
curl -X POST https://era-agent.yawnxyz.workers.dev/api/sessions \
  -H "Content-Type: application/json" \
  -d '{
    "language": "python",
    "session_id": "my-session",
    "data": {
      "user_id": "123",
      "workspace": "analytics"
    }
  }'

# Retrieve metadata later
curl https://era-agent.yawnxyz.workers.dev/api/sessions/my-session

What Doesn’t Persist?

Across Different Sessions

Each session is isolated - nothing persists between different sessions:

# Session A
curl -X POST https://era-agent.yawnxyz.workers.dev/api/sessions/session-a/run \
  -H "Content-Type: application/json" \
  -d '{
    "code": "shared_data = \"This is session A\""
  }'

# Session B - can't access session-a's data
curl -X POST https://era-agent.yawnxyz.workers.dev/api/sessions/session-b/run \
  -H "Content-Type: application/json" \
  -d '{
    "code": "print(shared_data)"  # Error: name \"shared_data\" is not defined
  }'

One-Shot Executions

The /api/execute endpoint creates temporary sessions that are immediately destroyed:

# First execution
curl -X POST https://era-agent.yawnxyz.workers.dev/api/execute \
  -H "Content-Type: application/json" \
  -d '{
    "language": "python",
    "code": "data = [1, 2, 3]"
  }'

# Second execution - fresh environment
curl -X POST https://era-agent.yawnxyz.workers.dev/api/execute \
  -H "Content-Type: application/json" \
  -d '{
    "language": "python",
    "code": "print(data)"  # Error: name \"data\" is not defined
  }'

Persistence Patterns

Configuration Files

Store configuration that persists across runs:

# Initialize configuration
curl -X POST https://era-agent.yawnxyz.workers.dev/api/sessions/app-session/run \
  -H "Content-Type: application/json" \
  -d '{
    "code": "import json\nconfig = {\"api_url\": \"https://api.example.com\", \"timeout\": 30}\nwith open(\"config.json\", \"w\") as f:\n    json.dump(config, f)"
  }'

# Load configuration in any run
curl -X POST https://era-agent.yawnxyz.workers.dev/api/sessions/app-session/run \
  -H "Content-Type: application/json" \
  -d '{
    "code": "import json\nwith open(\"config.json\", \"r\") as f:\n    config = json.load(f)\nprint(f\"API URL: {config[\"api_url\"]}\")"
  }'

Data Accumulation

Build up data over multiple runs:

# Initialize log
curl -X POST https://era-agent.yawnxyz.workers.dev/api/sessions/logger/run \
  -H "Content-Type: application/json" \
  -d '{
    "code": "import json\nlog = []\nwith open(\"log.json\", \"w\") as f:\n    json.dump(log, f)"
  }'

# Add entry 1
curl -X POST https://era-agent.yawnxyz.workers.dev/api/sessions/logger/run \
  -H "Content-Type: application/json" \
  -d '{
    "code": "import json\nwith open(\"log.json\", \"r\") as f:\n    log = json.load(f)\nlog.append({\"event\": \"user_login\", \"time\": \"10:00\"})\nwith open(\"log.json\", \"w\") as f:\n    json.dump(log, f)\nprint(f\"Log entries: {len(log)}\")"
  }'

# Add entry 2
curl -X POST https://era-agent.yawnxyz.workers.dev/api/sessions/logger/run \
  -H "Content-Type: application/json" \
  -d '{
    "code": "import json\nwith open(\"log.json\", \"r\") as f:\n    log = json.load(f)\nlog.append({\"event\": \"user_action\", \"time\": \"10:05\"})\nwith open(\"log.json\", \"w\") as f:\n    json.dump(log, f)\nprint(f\"Log entries: {len(log)}\")"
  }'

State Machine

Implement workflows with persistent state:

# Initialize workflow
curl -X POST https://era-agent.yawnxyz.workers.dev/api/sessions/workflow/run \
  -H "Content-Type: application/json" \
  -d '{
    "code": "state = \"initialized\"\nsteps_completed = 0\nprint(f\"State: {state}\")"
  }'

# Step 1: Collect data
curl -X POST https://era-agent.yawnxyz.workers.dev/api/sessions/workflow/run \
  -H "Content-Type: application/json" \
  -d '{
    "code": "if state == \"initialized\":\n    data = [1, 2, 3, 4, 5]\n    state = \"data_collected\"\n    steps_completed += 1\n    print(f\"Data collected. State: {state}\")\nelse:\n    print(f\"Invalid state: {state}\")"
  }'

# Step 2: Process data
curl -X POST https://era-agent.yawnxyz.workers.dev/api/sessions/workflow/run \
  -H "Content-Type: application/json" \
  -d '{
    "code": "if state == \"data_collected\":\n    result = sum(data) / len(data)\n    state = \"processed\"\n    steps_completed += 1\n    print(f\"Average: {result}. State: {state}\")\nelse:\n    print(f\"Invalid state: {state}\")"
  }'

# Step 3: Complete
curl -X POST https://era-agent.yawnxyz.workers.dev/api/sessions/workflow/run \
  -H "Content-Type: application/json" \
  -d '{
    "code": "if state == \"processed\":\n    state = \"completed\"\n    print(f\"Workflow completed in {steps_completed} steps\")\nelse:\n    print(f\"Invalid state: {state}\")"
  }'

Cache Pattern

Cache expensive computations:

# First run - compute and cache
curl -X POST https://era-agent.yawnxyz.workers.dev/api/sessions/cache-demo/run \
  -H "Content-Type: application/json" \
  -d '{
    "code": "import json\nimport os\n\ndef expensive_computation(n):\n    result = sum(range(n))\n    return result\n\ncache_file = \"cache.json\"\nif os.path.exists(cache_file):\n    with open(cache_file, \"r\") as f:\n        cache = json.load(f)\n    print(\"Using cached result\")\nelse:\n    result = expensive_computation(1000000)\n    cache = {\"result\": result}\n    with open(cache_file, \"w\") as f:\n        json.dump(cache, f)\n    print(\"Computed and cached result\")\n\nprint(f\"Result: {cache[\"result\"]}\")"
  }'

# Second run - uses cache
curl -X POST https://era-agent.yawnxyz.workers.dev/api/sessions/cache-demo/run \
  -H "Content-Type: application/json" \
  -d '{
    "code": "import json\nwith open(\"cache.json\", \"r\") as f:\n    cache = json.load(f)\nprint(f\"Cached result: {cache[\"result\"]}\")"
  }'

Session Data Updates

Update session metadata during execution:

curl -X POST https://era-agent.yawnxyz.workers.dev/api/sessions/my-session/run \
  -H "Content-Type: application/json" \
  -d '{
    "code": "result = 42\nprint(f\"Computed: {result}\")",
    "update_data": {
      "last_result": 42,
      "computation_count": 1,
      "updated_at": "2024-10-23T10:30:00Z"
    }
  }'

# Retrieve updated metadata
curl https://era-agent.yawnxyz.workers.dev/api/sessions/my-session

Best Practices

Initialize Session State

# Create initialization script
curl -X POST https://era-agent.yawnxyz.workers.dev/api/sessions/my-session/run \
  -H "Content-Type: application/json" \
  -d '{
    "code": "# Initialize session\nimport json\nimport os\n\n# Set up config if not exists\nif not os.path.exists(\"config.json\"):\n    config = {\"version\": \"1.0\", \"initialized\": True}\n    with open(\"config.json\", \"w\") as f:\n        json.dump(config, f)\n\n# Initialize state\nif \"state\" not in dir():\n    state = {\"runs\": 0}\n\nprint(\"Session initialized\")"
  }'

Check File Existence

curl -X POST https://era-agent.yawnxyz.workers.dev/api/sessions/my-session/run \
  -H "Content-Type: application/json" \
  -d '{
    "code": "import os\nimport json\n\ndata_file = \"data.json\"\n\nif os.path.exists(data_file):\n    with open(data_file, \"r\") as f:\n        data = json.load(f)\n    print(f\"Loaded existing data: {len(data)} items\")\nelse:\n    data = []\n    print(\"Initialized new data\")\n\n# Add new item\ndata.append({\"value\": 42})\n\n# Save\nwith open(data_file, \"w\") as f:\n    json.dump(data, f)"
  }'

Version Control

curl -X POST https://era-agent.yawnxyz.workers.dev/api/sessions/my-session/run \
  -H "Content-Type: application/json" \
  -d '{
    "code": "import json\n\nVERSION = \"2.0\"\n\ntry:\n    with open(\"data.json\", \"r\") as f:\n        data = json.load(f)\n    \n    # Migrate if needed\n    if data.get(\"version\", \"1.0\") != VERSION:\n        print(f\"Migrating from {data.get(\"version\")} to {VERSION}\")\n        # Perform migration...\n        data[\"version\"] = VERSION\n        with open(\"data.json\", \"w\") as f:\n            json.dump(data, f)\nexcept FileNotFoundError:\n    data = {\"version\": VERSION, \"items\": []}\n    with open(\"data.json\", \"w\") as f:\n        json.dump(data, f)"
  }'