ReflexioDeveloper Docs
Enterprise startGitHubWebsite
Menu
GitHubWebsitellms.txt

Configuration Guide

Complete reference for all Reflexio configuration options including profile extraction, playbook, and evaluation settings.

Configuration Guide

This guide explains all configuration options available in Reflexio. Configuration controls how profiles are extracted, playbooks are generated, and agent performance is evaluated.

Overview

Reflexio uses a centralized Config object that contains settings for:

Getting and Setting Configuration

Configure Reflexio programmatically using the client when you want to override defaults. There are two ways to write config, depending on what you're changing:

  • update_config — a partial (PATCH-style) update of one or more top-level fields. The server merges your changes into the existing config atomically, so you only send the fields you're changing. This is the recommended way to override a single default.
  • get_config → set_config — fetch the full config, modify it, and send it back. Use this when you need to replace a nested object (e.g. an extractor config) wholesale.

Enterprise

If you're using Reflexio Enterprise, you can also configure settings visually via the web portal under the Settings page.

Send only the top-level fields you want to change:

from reflexio import ReflexioClient

client = ReflexioClient()  # uses REFLEXIO_API_KEY env var
# Self-hosted: client = ReflexioClient(url_endpoint="http://localhost:8081")

# Override one or more top-level fields — no need to re-send the full config
client.update_config({"window_size": 20, "stride_size": 10})
curl -X POST "http://localhost:8081/api/update_config" \
  -H "User-Agent: my-agent-reflexio" \
  -H "Authorization: Bearer $REFLEXIO_API_KEY" \
  -H "Content-Type: application/json" \
  --data '{"window_size": 20, "stride_size": 10}'

update_config does a top-level shallow merge — nested objects (e.g. profile_extractor_config, storage_config) are replaced wholesale, not deep-merged. To change a single field inside a nested object, use the full-config round-trip below.

Full / nested edits

Fetch the config, modify a nested object, and send the whole thing back:

from reflexio import ReflexioClient

client = ReflexioClient()  # uses REFLEXIO_API_KEY env var
# Self-hosted: client = ReflexioClient(url_endpoint="http://localhost:8081")

# Get current configuration
config = client.get_config()

# Modify a nested config object
config.profile_extractor_config = ...

# Save the full configuration
client.set_config(config)
curl -X GET "http://localhost:8081/api/get_config" \
  -H "User-Agent: my-agent-reflexio" \
  -H "Authorization: Bearer $REFLEXIO_API_KEY"

curl -X POST "http://localhost:8081/api/set_config" \
  -H "User-Agent: my-agent-reflexio" \
  -H "Authorization: Bearer $REFLEXIO_API_KEY" \
  -H "Content-Type: application/json" \
  --data @- <<'JSON'
{
  "...": "updated full config object"
}
JSON

General Settings

Agent Context

Optionally provide global context about the agent's environment that should be shared across all extractors and evaluations.

config.agent_context_prompt = """
This agent is a customer service representative for an e-commerce platform.
The agent helps customers with:
- Product inquiries and recommendations
- Order tracking and status updates
- Returns and refunds
- Technical support for the website
"""

Extraction Window Configuration

Reflexio uses a sliding window to group interactions for extraction. This controls how many interactions are processed together and how frequently extraction runs.

config.window_size = 10  # Number of interactions per extraction
config.stride_size = 5  # New interactions before next extraction
FieldTypeDescription
window_sizeintNumber of interactions included in each extraction window.
stride_sizeintNumber of new interactions that trigger the next extraction.
skip_should_run_checkboolSkip the LLM pre-extraction eligibility check — extraction always runs. Default: False.

Example: With window_size=10 and stride_size=5:

  • First extraction processes interactions 1-10
  • After 5 new interactions arrive, next extraction processes interactions 6-15
  • After 5 more, next extraction processes interactions 11-20

This overlapping window ensures context continuity between extractions while avoiding redundant processing of every single interaction.

Complete Configuration Example

from reflexio import ReflexioClient
from reflexio.models.config_schema import (
    Config,
    ProfileExtractorConfig,
    UserPlaybookExtractorConfig,
    PlaybookAggregatorConfig,
    AgentSuccessConfig,
    ToolUseConfig
)

client = ReflexioClient()  # see Quickstart for connection options

# Get current config (storage defaults to SQLite — no configuration needed)
config = client.get_config()

# Configure agent context
config.agent_context_prompt = """
Customer service agent for an online booking platform.
Helps users book hotels, flights, and activities.
"""

# Optional: customize profile extraction
config.profile_extractor_config = ProfileExtractorConfig(
    extraction_definition_prompt="""
    Extract: name, travel preferences, budget range,
    frequent destinations, loyalty program status
    """,
    context_prompt="Travel booking conversation",
    metadata_definition_prompt="category: 'traveler_profile'"
)

# Optional: customize playbook collection
config.user_playbook_extractor_config = UserPlaybookExtractorConfig(
    extraction_definition_prompt="""
    Was the booking process smooth? Any pain points?
    Did the agent provide helpful recommendations?
    """,
    aggregation_config=PlaybookAggregatorConfig(
        min_cluster_size=10,
        reaggregation_trigger_count=5
    )
)

# Configure tools the agent can use (shared across evaluation and extraction)
config.tool_can_use = [
    ToolUseConfig(
        tool_name="search_availability",
        tool_description="Search available options"
    ),
    ToolUseConfig(
        tool_name="create_reservation",
        tool_description="Create a new reservation"
    )
]

# Configure success evaluation (enabled by default at 5% sampling)
config.agent_success_config = AgentSuccessConfig(
    success_definition_prompt="""
    Success: Customer completed a booking or has clear next steps.
    Failure: Customer left confused, frustrated, or without resolution.
    """,
    sampling_rate=1.0
)

# Configure extraction windows
config.window_size = 20
config.stride_size = 10

# Save configuration
client.set_config(config)
curl -X GET "${REFLEXIO_URL:-https://www.reflexio.ai}/api/get_config" \
  -H "User-Agent: my-agent-reflexio" \
  -H "Authorization: Bearer $REFLEXIO_API_KEY"

curl -X POST "${REFLEXIO_URL:-https://www.reflexio.ai}/api/set_config" \
  -H "User-Agent: my-agent-reflexio" \
  -H "Authorization: Bearer $REFLEXIO_API_KEY" \
  -H "Content-Type: application/json" \
  --data @- <<'JSON'
{
  "...": "updated full config object"
}
JSON

Best Practices

  1. Start with the defaults - Publish real interactions before tuning profile_extractor_config or user_playbook_extractor_config

  2. Customize prompts after review - Once you see real extracted profiles and playbooks, make prompt overrides specific. Vague prompts lead to inconsistent results

  3. Review evaluation samples - Agent success evaluation is enabled by default with sampling_rate=0.05. Increase it for launches or audits, and lower it if you need tighter cost control

  4. Monitor playbook thresholds - Set min_cluster_size high enough to get meaningful aggregations

  5. Filter by source - Use request_sources_enabled to process only relevant interaction types

  6. Iterate on definitions - Review extracted profiles and adjust prompts based on results

Next Steps