Collecting and Using Playbooks

Reflexio ships with a default playbook extractor. Published corrections and successful procedures become user playbooks; recurring patterns can aggregate into agent playbooks for human approval.

Collect Useful Evidence

Publish the complete turn, including the user's correction or confirmation, and set agent_version consistently.

client.publish_interaction(
    user_id="customer_123",
    session_id="billing_001",
    source="support_chat",
    agent_version="support-agent@2.4.0",
    interactions=[
        {"role": "User", "content": "Please update my billing email."},
        {"role": "Agent", "content": "Done—the email is now changed."},
        {
            "role": "User",
            "content": "You must verify account ownership before changing billing details.",
        },
    ],
)

Use expert_content when an expert has supplied the preferred response. Do not manufacture positive feedback merely to trigger extraction.

Retrieve Guidance

Unified search is the recommended serving path:

context = client.search(
    query="user wants to change sensitive account details",
    user_id="customer_123",
    agent_version="support-agent@2.4.0",
    entity_types=["user_playbooks", "agent_playbooks"],
    agent_playbook_status_filter=["approved"],
    top_k=5,
)

When an agent playbook represents a returned source user playbook, Reflexio suppresses the duplicate user playbook. Result arrays may therefore contain fewer than top_k items.

Inspect User Playbooks

Use get_user_playbooks to inspect source-level guidance or filter by user, request, playbook name, agent version, status, time, or tag. Use search_user_playbooks when semantic relevance matters.

evidence = client.get_user_playbooks(
    user_id="customer_123",
    agent_version="support-agent@2.4.0",
    status_filter=[None],
)

Aggregate and Review Agent Playbooks

Aggregation normally runs according to configuration. Operators can also trigger it explicitly for an agent version:

client.run_playbook_aggregation(
    agent_version="support-agent@2.4.0",
    wait_for_response=True,
)

Review pending results in the Hosted Enterprise portal or with get_agent_playbooks, then update status to approved or rejected.

Customize Carefully

Tune the playbook definition only after reviewing actual extracted evidence. Keep it behavioral and actionable; user facts belong in profiles.

client.update_config({
    "user_playbook_extractor_config": {
        "extraction_definition_prompt": (
            "Extract reusable procedures and explicit corrections about handling sensitive account changes."
        ),
        "aggregation_config": {
            "min_cluster_size": 3,
            "reaggregation_trigger_count": 2,
        },
    }
})

Nested objects are replaced rather than deep-merged, so preserve any existing nested fields you still need.

For the two-scope lifecycle, see Playbooks. For every management method and schema, see the Playbook API Reference.