Skip to main content
Sessions can store arbitrary configuration data that persists for the session lifetime. Use configs to track agent settings, model parameters, or any session-level metadata.

​
Create Session with Configs

session = client.sessions.create(
    configs={"agent": "bot1", "temperature": 0.7, "model": "gpt-4"}
)

​
Update Configs (Full Replacement)

Use update_configs to completely replace all configs. Any keys not included will be removed. 
# Replaces ALL configs - any missing keys are deleted
client.sessions.update_configs(
    session_id=session.id,
    configs={"agent": "bot2", "temperature": 0.9}  # "model" key is now gone
)

​
Patch Configs (Partial Update)

Use patch_configs to update only specific keys while preserving others. Pass null/None to delete a key. 
# Add or update keys (preserves existing keys)
updated = client.sessions.patch_configs(
    session_id=session.id,
    configs={"agent": "bot2", "new_setting": True}
)
print(updated)  # {"agent": "bot2", "temperature": 0.7, "model": "gpt-4", "new_setting": True}

# Delete a key by passing None
updated = client.sessions.patch_configs(
    session_id=session.id,
    configs={"model": None}  # Deletes "model" key
)
print(updated)  # {"agent": "bot2", "temperature": 0.7, "new_setting": True}

​
PUT vs PATCH Comparison

AspectPUT (update_configs)PATCH (patch_configs)
SemanticsFull replacementPartial update
Missing keysRemovedPreserved
Null valuesSet to nullDelete the key
Return valueNoneUpdated configs

​
Get Configs

session = client.sessions.get_configs(session_id=session.id)
print(session.configs)

​
Filter Sessions by Configs

Filter sessions by their configs metadata using JSONB containment. Only sessions where configs contains all key-value pairs in your filter will be returned.

​
Basic Usage

import os
from acontext import AcontextClient

client = AcontextClient(api_key=os.getenv("ACONTEXT_API_KEY"))

# Create sessions with configs
session1 = client.sessions.create(configs={"agent": "bot1", "env": "prod"})
session2 = client.sessions.create(configs={"agent": "bot2", "env": "dev"})

# Filter by single key
sessions = client.sessions.list(filter_by_configs={"agent": "bot1"})
# Returns: session1

​
Filter Examples

​
Multiple Keys

Sessions must match all key-value pairs: 
# Only returns sessions with BOTH agent="bot1" AND env="prod"
sessions = client.sessions.list(
    filter_by_configs={"agent": "bot1", "env": "prod"}
)

​
Nested Objects

Filter by nested config values: 
# Create session with nested config
session = client.sessions.create(
    configs={"agent": {"name": "bot1", "version": "2.0"}}
)

# Filter by nested object
sessions = client.sessions.list(
    filter_by_configs={"agent": {"name": "bot1"}}
)

​
Combine with User Filter

# Filter by both user and configs
sessions = client.sessions.list(
    user="alice@example.com",
    filter_by_configs={"agent": "bot1"}
)

​
Important Behaviors

  • Case-sensitive: {"Agent": "x"} won’t match {"agent": "x"}
  • Type-sensitive: {"count": 1} won’t match {"count": "1"}
  • Partial matching: filter {"a": 1} matches configs {"a": 1, "b": 2}
  • NULL excluded: Sessions with configs=null are excluded from filtered results

​
Next Steps

Message Metadata

Attach metadata to individual messages

Multi-provider Messages

Store messages in any format