Guides

Requests and Sessions

Learn how requests and sessions organize interactions in Reflexio for structured tracking and bulk operations.

Overview

Requests and sessions are the organizational foundation of Reflexio, enabling structured tracking and bulk operations on user interactions.

Core Definitions

Request

A published batch of interactions, with source, agent-version, and session context.

Session

Related requests that belong to one conversation or user journey.

A Request is a container for one or more interactions that provides source, agent-version, and session context. Every time you publish interactions using publish_interaction(), Reflexio creates a Request object that wraps those interactions.

Request Structure

Each Request contains:

Field	Type	Description
`request_id`	`string`	Unique identifier (UUID) automatically generated by the server
`user_id`	`string`	The user associated with this request
`source`	`string`	A non-sensitive producer/workflow label. A non-empty value must match `^[a-z0-9][a-z0-9._:-]{0,127}$` and must not contain user identifiers or PII
`agent_version`	`string`	Version of your agent that generated this interaction
`session_id`	`string`	Required non-empty string that groups related requests together
`created_at`	`integer`	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:

Python

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
    )

Terminal

curl -X POST "${REFLEXIO_URL:-https://www.reflexio.ai}/api/publish_interaction" \
  -H "User-Agent: my-agent-reflexio" \
  -H "Authorization: Bearer $REFLEXIO_API_KEY" \
  -H "Content-Type: application/json" \
  --data @- <<'JSON'
{
  "user_id": "user_123",
  "interaction_data_list": [
    "<interaction>"
  ],
  "session_id": "session_xyz"
}
JSON

2. Multi-Turn Conversation Tracking

Publish multiple turns of a conversation under the same session for better context:

Python

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"
)

Terminal

curl -X POST "${REFLEXIO_URL:-https://www.reflexio.ai}/api/publish_interaction" \
  -H "User-Agent: my-agent-reflexio" \
  -H "Authorization: Bearer $REFLEXIO_API_KEY" \
  -H "Content-Type: application/json" \
  --data @- <<'JSON'
{
  "user_id": "user_123",
  "interaction_data_list": [
    {
      "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": "conv_20241215_001",
  "agent_version": "v1.0"
}
JSON

curl -X POST "${REFLEXIO_URL:-https://www.reflexio.ai}/api/publish_interaction" \
  -H "User-Agent: my-agent-reflexio" \
  -H "Authorization: Bearer $REFLEXIO_API_KEY" \
  -H "Content-Type: application/json" \
  --data @- <<'JSON'
{
  "user_id": "user_123",
  "interaction_data_list": [
    {
      "role": "User",
      "content": "Order #12345"
    },
    {
      "role": "Agent",
      "content": "I found your order. It's currently being shipped."
    }
  ],
  "session_id": "conv_20241215_001",
  "agent_version": "v1.0"
}
JSON

3. Bulk Cleanup

Delete all requests from a session or conversation at once:

Python

# After session concludes, clean up all data
client.delete_session(
    session_id="session_001",
    wait_for_response=True
)

Terminal

curl -X DELETE "${REFLEXIO_URL:-https://www.reflexio.ai}/api/delete_session" \
  -H "User-Agent: my-agent-reflexio" \
  -H "Authorization: Bearer $REFLEXIO_API_KEY" \
  -H "Content-Type: application/json" \
  --data @- <<'JSON'
{
  "session_id": "session_001"
}
JSON

Workflow Example

Here's a complete workflow showing how requests and sessions work together:

Python

from reflexio import ReflexioClient

client = ReflexioClient()  # uses REFLEXIO_API_KEY env var
# Local OSS: 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
)

Terminal

curl -X POST "http://localhost:8081/api/publish_interaction" \
  -H "User-Agent: my-agent-reflexio" \
  -H "Authorization: Bearer $REFLEXIO_API_KEY" \
  -H "Content-Type: application/json" \
  --data @- <<'JSON'
{
  "user_id": "user_456",
  "interaction_data_list": [
    {
      "content": "User asks a question",
      "role": "user"
    },
    {
      "content": "Agent response",
      "role": "assistant"
    }
  ],
  "session_id": "session_001",
  "agent_version": "v2.0",
  "source": "web_app"
}
JSON

curl -X POST "http://localhost:8081/api/get_requests" \
  -H "User-Agent: my-agent-reflexio" \
  -H "Authorization: Bearer $REFLEXIO_API_KEY" \
  -H "Content-Type: application/json" \
  --data @- <<'JSON'
{
  "user_id": "user_456"
}
JSON

curl -X DELETE "http://localhost:8081/api/delete_session" \
  -H "User-Agent: my-agent-reflexio" \
  -H "Authorization: Bearer $REFLEXIO_API_KEY" \
  -H "Content-Type: application/json" \
  --data @- <<'JSON'
{
  "session_id": "session_001"
}
JSON

Best Practices

1. Use Descriptive Session Names

Python

# 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:

Python

client.publish_interaction(
    user_id="user_123",
    interactions=[...],
    agent_version="v2.1.0",  # Clear version tracking
    session_id="session_001"
)

Terminal

curl -X POST "${REFLEXIO_URL:-https://www.reflexio.ai}/api/publish_interaction" \
  -H "User-Agent: my-agent-reflexio" \
  -H "Authorization: Bearer $REFLEXIO_API_KEY" \
  -H "Content-Type: application/json" \
  --data @- <<'JSON'
{
  "user_id": "user_123",
  "interaction_data_list": [
    "<...>"
  ],
  "agent_version": "v2.1.0",
  "session_id": "session_001"
}
JSON

3. Clean Up Completed Sessions

Delete sessions when they are no longer needed to manage storage:

Python

# After analysis is complete
client.delete_session(
    session_id="old_session_001",
    wait_for_response=True
)

Terminal

curl -X DELETE "${REFLEXIO_URL:-https://www.reflexio.ai}/api/delete_session" \
  -H "User-Agent: my-agent-reflexio" \
  -H "Authorization: Bearer $REFLEXIO_API_KEY" \
  -H "Content-Type: application/json" \
  --data @- <<'JSON'
{
  "session_id": "old_session_001"
}
JSON

4. Use Source for Attribution

Track where interactions came from:

Python

client.publish_interaction(
    user_id="user_123",
    interactions=[...],
    source="mobile_app",  # or "web_app", "api", etc.
    session_id="session_001"
)

Terminal

curl -X POST "${REFLEXIO_URL:-https://www.reflexio.ai}/api/publish_interaction" \
  -H "User-Agent: my-agent-reflexio" \
  -H "Authorization: Bearer $REFLEXIO_API_KEY" \
  -H "Content-Type: application/json" \
  --data @- <<'JSON'
{
  "user_id": "user_123",
  "interaction_data_list": [
    "<...>"
  ],
  "source": "mobile_app",
  "session_id": "session_001"
}
JSON

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 interactions
get_requests(): Retrieve requests grouped by session
delete_request(): Delete a single request
delete_session(): Delete all requests in a session

Examples

See Request Management Examples for detailed code examples.

Request

Session

Publishing Interactions

Working with User Profiles

Collecting and Using Playbooks

API Reference