Requests and Sessions
Learn how requests and sessions organize interactions in Reflexio for structured tracking and bulk operations.
Requests and Sessions
Overview
Requests and sessions are the organizational foundation of Reflexio, enabling structured tracking and bulk operations on user interactions.
What is a Request?
A Request is a container for one or more interactions that provides essential metadata and organizational context. Every time you publish interactions using publish_interaction(), Reflexio creates a Request object that wraps those interactions.
Request Structure
Each Request contains:
request_id: Unique identifier (UUID) automatically generated by the serveruser_id: The user associated with this requestsource: Where the interaction came from (e.g., "web_app", "mobile_app", "api")agent_version: Version of your agent that generated this interactionsession_id: Optional string to group related requests togethercreated_at: Timestamp when the request was created
Why Requests Matter
Requests provide:
- Attribution: Track which agent version or source generated which interactions
- Organization: Group related interactions together
- Bulk Operations: Delete all interactions from a request at once
Sessions
Sessions are logical groupings of related requests that belong to the same conversation or session. They serve a critical role in providing context for profile and playbook extraction.
Why Sessions Matter
When Reflexio processes interactions for profile extraction or playbook generation, it uses the session to understand the broader context. All requests within the same session are considered part of the same conversation, allowing the system to:
- Extract more accurate profiles - Understanding the full conversation context leads to better profile extraction
- Generate contextual playbook entries - Playbook generation can consider the entire session flow
- Maintain conversation continuity - Related requests are linked together for analysis
Use Cases
1. Conversation/Session Tracking
Group all requests within a user conversation or session:
session_id = "session_xyz"
# Multiple interactions in the same session
for interaction in session_interactions:
client.publish_interaction(
user_id="user_123",
interactions=[interaction],
session_id=session_id
)2. Multi-Turn Conversation Tracking
Publish multiple turns of a conversation under the same session for better context:
conversation_id = "conv_20241215_001"
# First turn
client.publish_interaction(
user_id="user_123",
interactions=[
{"role": "User", "content": "I need help with my order"},
{"role": "Agent", "content": "I'd be happy to help! What's your order number?"}
],
session_id=conversation_id,
agent_version="v1.0"
)
# Second turn (same conversation)
client.publish_interaction(
user_id="user_123",
interactions=[
{"role": "User", "content": "Order #12345"},
{"role": "Agent", "content": "I found your order. It's currently being shipped."}
],
session_id=conversation_id,
agent_version="v1.0"
)3. Bulk Cleanup
Delete all requests from a session or conversation at once:
# After session concludes, clean up all data
client.delete_session(
session_id="session_001",
wait_for_response=True
)Workflow Example
Here's a complete workflow showing how requests and sessions work together:
from reflexio import ReflexioClient
client = ReflexioClient() # uses REFLEXIO_API_KEY env var
# Self-hosted: client = ReflexioClient(url_endpoint="http://localhost:8081")
# Step 1: Publish interaction
client.publish_interaction(
user_id="user_456",
interactions=[
{"content": "User asks a question", "role": "user"},
{"content": "Agent response", "role": "assistant"}
],
session_id="session_001",
agent_version="v2.0",
source="web_app"
)
# Step 2: Retrieve all requests for the user
requests = client.get_requests(user_id="user_456")
# Step 3: Analyze requests
for session in requests.sessions:
print(f"Session: {session.session_id}")
for request_data in session.requests:
print(f" Request ID: {request_data.request.request_id}")
print(f" Agent Version: {request_data.request.agent_version}")
print(f" Interactions: {len(request_data.interactions)}")
# Step 4: Clean up after analysis
client.delete_session(
session_id="session_001",
wait_for_response=True
)Best Practices
1. Use Descriptive Session Names
# Good: Clear, descriptive names
session_id="2024_q1_session_001"
session_id="onboarding_flow_v3"
# Avoid: Generic or unclear names
session_id="test1"
session_id="experiment"2. Track Agent Versions
Always specify agent_version to track which version generated each request:
client.publish_interaction(
user_id="user_123",
interactions=[...],
agent_version="v2.1.0", # Clear version tracking
session_id="session_001"
)3. Clean Up Completed Sessions
Delete sessions when they are no longer needed to manage storage:
# After analysis is complete
client.delete_session(
session_id="old_session_001",
wait_for_response=True
)4. Use Source for Attribution
Track where interactions came from:
client.publish_interaction(
user_id="user_123",
interactions=[...],
source="mobile_app", # or "web_app", "api", etc.
session_id="session_001"
)Related Concepts
- Interactions: The individual data points contained within requests
- User Profiles: Generated from requests
- Agent Playbooks: Generated from requests
API Reference
publish_interaction(): Create requests with interactionsget_requests(): Retrieve requests grouped by sessiondelete_request(): Delete a single requestdelete_session(): Delete all requests in a session
Examples
See Request Management Examples for detailed code examples.