Session Configuration

Sessions let resources persist values across multiple requests from the same caller using set('key', val, 'session'). Configure the storage backend in workflow.yaml under settings.session:.

Type	Persistence	Use Case
sqlite	File-based, survives restart	Production, multi-container
memory	In-memory only, lost on restart	Development, single instance

Configuration

# workflow.yaml
settings:
  session:
    type: sqlite                    # "sqlite" or "memory"
    path: ".kdeps/sessions.db"      # SQLite file path
    ttl: "30m"                      # Session expiration
    cleanupInterval: "5m"           # Cleanup frequency

Session Types

SQLite (recommended for production)

Persists to a file -- survives restarts and can be shared via a mounted volume.

# workflow.yaml
settings:
  session:
    type: sqlite
    path: "/data/sessions.db"   # absolute or relative path
    ttl: "24h"                  # how long a session lives without activity
    cleanupInterval: "1h"       # how often expired sessions are purged

Memory

Fast (no disk I/O) but lost on restart. Use for development or single-instance setups.

# workflow.yaml
settings:
  session:
    type: memory
    ttl: "30m"
    cleanupInterval: "5m"

TTL (Time To Live)

Session expiration durations:

# workflow.yaml
ttl: "30s"    # 30 seconds
ttl: "5m"     # 5 minutes
ttl: "1h"     # 1 hour
ttl: "24h"    # 24 hours
ttl: "7d"     # 7 days (168h)

Using Sessions

Store Data

# resources/example.yaml
after:
  # Store user ID
  - set('user_id', '123', 'session')

  # Store preferences
  - set('theme', 'dark', 'session')

  # Increment counter
  - set('visits', get('visits', 'session') + 1, 'session')

Retrieve Data

# resources/example.yaml
chat:
  prompt: |
    User {{ get('user_id', 'session') }} prefers {{ get('theme', 'session') }}.
    This is visit #{{ get('visits', 'session') }}.

Examples

Login Session

# Login resource
actionId: login

validations:
  check:
    - get('username') != ''
    - get('password') != ''
  error:
    code: 400
    message: Username and password required

after:
  # Validate credentials (simplified)
  - set('authenticated', get('username') == 'admin', 'session')
  - set('user', get('username'), 'session')
  - set('login_time', info('timestamp'), 'session')

apiResponse:
  success: get('authenticated', 'session')
  response:
    message: "{{ get('authenticated', 'session') ? 'Login successful' : 'Invalid credentials' }}"

Protected Route

# resources/example.yaml
actionId: protectedResource

validations:
  check:
    - get('authenticated', 'session') == true
  error:
    code: 401
    message: Authentication required

chat:
  prompt: "Hello {{ get('user', 'session') }}, how can I help?"

Shopping Cart

# Add to cart
actionId: addToCart

after:
  - set('cart', get('cart', 'session') + [get('item')], 'session')

apiResponse:
  success: true
  response:
    cart: get('cart', 'session')
    count: len(get('cart', 'session'))

---
# View cart
actionId: viewCart

apiResponse:
  success: true
  response:
    items: get('cart', 'session')
    total: sum(map(get('cart', 'session'), .price))

User Preferences

# Save preferences
actionId: savePrefs

after:
  - set('language', get('language', 'en'), 'session')
  - set('timezone', get('timezone', 'UTC'), 'session')
  - set('theme', get('theme', 'light'), 'session')

apiResponse:
  success: true
  response:
    message: Preferences saved

---
# Apply preferences
actionId: getContent

chat:
  prompt: |
<div v-pre>
      Respond in {{ get('language', 'session') }}.
      Current time in {{ get('timezone', 'session') }}: {{ info('timestamp') }}
</div>

Session ID

Each session has a unique ID accessible via:

# resources/example.yaml
session_id: info('sessionId')

The session ID is typically stored in a cookie or passed as a header.

Cleanup

Expired sessions are automatically cleaned up based on cleanupInterval:

# resources/example.yaml
session:
  ttl: "30m"              # Sessions expire after 30 minutes
  cleanupInterval: "5m"   # Check for expired sessions every 5 minutes

Docker Considerations

Persistent Volume

For SQLite sessions in Docker:

# docker-compose.yml
services:
  myagent:
    volumes:
      - session_data:/data

volumes:
  session_data:

# workflow.yaml
settings:
  session:
    type: sqlite
    path: "/data/sessions.db"

Shared Sessions

For multiple containers sharing sessions:

1. Use a shared volume for SQLite
2. Or use an external session store (Redis, PostgreSQL)

Best Practices

1. Use SQLite for production - Survives restarts
2. Set appropriate TTL - Balance security and convenience
3. Store minimal data - Session storage is not a database
4. Handle missing sessions - Always provide defaults
5. Secure sensitive data - Don't store passwords in sessions

Security Notes

• Sessions are identified by a unique ID
• Session IDs should be transmitted securely (HTTPS)
• Implement logout by clearing session data
• Set reasonable TTL to limit exposure

See Also

• Workflow Configuration - Full settings reference
• Unified API - get() and set() usage
• Docker Deployment - Production setup