ReflexioDeveloper Docs
Hosted Enterprise startGitHubWebsite
Menu
GitHubWebsitellms.txt
All

Interaction Management

Methods for publishing, searching, retrieving, and deleting user interactions.

Interaction Management

publish_interaction

Publish user interactions to the system. This is the primary method for sending data to Reflexio.

Async applications can call await client.publish_interaction_async(...) with the same parameters and return type. It uses native async HTTP, applies the client's total timeout, and preserves task cancellation.

response = client.publish_interaction(
    user_id,
    interactions,
    session_id="session_abc",
    source="",
    agent_version="agent-v0",
    wait_for_response=False,
    skip_aggregation=False,
    force_extraction=False,
    evaluation_only=False,
    override_learning_stall=False,
    retrieval_experiment_id=None,
    retrieval_experiment_arm=None,
)
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_id>",
  "interaction_data_list": "<interactions>",
  "session_id": "session_abc",
  "source": "",
  "agent_version": "agent-v0",
  "skip_aggregation": false,
  "force_extraction": false,
  "evaluation_only": false,
  "override_learning_stall": false,
  "retrieval_experiment_id": null,
  "retrieval_experiment_arm": null
}
JSON

Report the Reflexio context used by each response

If an agent response was produced with profiles or playbooks retrieved from Reflexio, add every injected learning to that response's retrieved_learnings. When the session is evaluated, Reflexio can then show whether each learning was relevant and whether its impact was positive, neutral, or negative. This attribution also provides the signal needed to improve future optimization of retrieved learnings. Omit the field only when no Reflexio learning was injected.

Prop

Type

Publish retrieval experiment attribution

When a learning-search response includes experiment, echo its experiment_id and arm on every related publish. Both treatment and holdout publish normally; do not set evaluation_only=True merely because the user is in holdout. Omit both fields when the search response has no experiment.

Returns: PublishUserInteractionResponse. In wait_for_response=False mode the response carries success, message, learning_status="deferred", and a request_id (so you can poll immediately); profile/playbook deltas are 0 because extraction has not run yet. In wait_for_response=True mode it also includes storage routing and real profile/playbook deltas. Use get_learning_status to poll for extraction progress after a deferred publish.

Raises pydantic.ValidationError locally, before any HTTP request, when an interaction is contradictory or the whole batch is empty:

  • every interaction is empty (no content, shadow_content, expert_content, interacted_image_url, image_encoding, tools_used, citations, retrieved_learnings, and a user_action of none)
  • a user_action other than none with no user_action_description
  • both interacted_image_url and image_encoding set

The message names the offending interaction_data_list index. Because this fires client-side, try/except around HTTP status codes will not catch it, and there is no response object with success=False — the equivalent over raw HTTP is a 422. A missing or blank session_id raises ValueError.

Individually empty interactions are dropped rather than raising, so one empty placeholder turn does not fail a batch that also carries real turns. Unrecognised keys are discarded, not rejected — but both the drops and the unbound field names are listed in the returned warnings, so check it rather than only success. See InteractionData.

Evaluation-Only Publish

Set evaluation_only=True when a session should be graded but should not teach Reflexio new profiles or playbooks, such as an offline candidate transcript. Do not use it for a retrieval-experiment holdout: both experiment arms should publish and learn normally so retrieval is the only controlled difference.

from reflexio import InteractionData, ReflexioClient

client = ReflexioClient()

client.publish_interaction(
    user_id="user_123",
    session_id="session_001",
    source="prod_without_reflexio",
    agent_version="v2.1.0",
    evaluation_only=True,
    interactions=[
        InteractionData(role="User", content="Can you help me reset my account password?"),
        InteractionData(role="Agent", content="Open Account Settings, choose Security, then select Reset Password."),
    ],
)
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",
  "session_id": "session_001",
  "source": "prod_without_reflexio",
  "agent_version": "v2.1.0",
  "evaluation_only": true,
  "interaction_data_list": [
    {
      "role": "User",
      "content": "Can you help me reset my account password?"
    },
    {
      "role": "Agent",
      "content": "Open Account Settings, choose Security, then select Reset Password."
    }
  ]
}
JSON

evaluation_only=True stores the request, schedules session-level success evaluation if the session passes agent_success_config.evaluation_only_sampling_rate, and excludes the request from profile extraction, playbook extraction, and aggregation. When that override is null, it inherits the current agent_success_config.sampling_rate. Retrieved-learning evaluation keeps its independent retrieved_learning_sampling_rate. The flag does not bypass the session inactivity delay, and it is not an experiment grouping dimension. Keep evaluation_only consistent across every publish in one session.

Interaction Dict Fields

Prop

Type

Example 1: Basic Text Conversation

# Simple conversation (fire-and-forget)
client.publish_interaction(
    user_id="user_123",
    interactions=[
        {"role": "User", "content": "What's the weather like?"},
        {"role": "Agent", "content": "It's sunny and 72°F today."}
    ],
    source="support-agent:v2",
    session_id="session_001"
)
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": "What's the weather like?"
    },
    {
      "role": "Agent",
      "content": "It's sunny and 72°F today."
    }
  ],
  "source": "support-agent:v2",
  "session_id": "session_001"
}
JSON

Example 2: Publish Retrieved Learnings

Attach every Reflexio profile or playbook injected into the agent's context to the response that used it. This enables per-learning relevance and impact analysis when the session is evaluated.

# Report the Reflexio context used to produce the agent response.
client.publish_interaction(
    user_id="user_123",
    interactions=[
        {"role": "User", "content": "Recommend a laptop for my next work trip."},
        {
            "role": "Agent",
            "content": "Choose a lightweight model with long battery life.",
            "retrieved_learnings": [
                {"kind": "profile", "learning_id": "prof-abc123"},
                {"kind": "user_playbook", "learning_id": "42"},
                {"kind": "agent_playbook", "learning_id": "7"},
            ],
        },
    ],
    session_id="session_001",
    source="support-agent:v2",
)
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": "Recommend a laptop for my next work trip."
    },
    {
      "role": "Agent",
      "content": "Choose a lightweight model with long battery life.",
      "retrieved_learnings": [
        {"kind": "profile", "learning_id": "prof-abc123"},
        {"kind": "user_playbook", "learning_id": "42"},
        {"kind": "agent_playbook", "learning_id": "7"}
      ]
    }
  ],
  "session_id": "session_001",
  "source": "support-agent:v2"
}
JSON

Example 3: Multi-Turn Conversation with Agent Version

# Track which agent version handled the interaction
client.publish_interaction(
    user_id="customer_456",
    interactions=[
        {"role": "User", "content": "I need help choosing a laptop"},
        {"role": "Agent", "content": "I'd be happy to help! What's your budget?"},
        {"role": "User", "content": "Around $1000 for programming work"},
        {"role": "Agent", "content": "For programming, I recommend the ThinkPad X1..."}
    ],
    source="support-agent:v2",
    agent_version="v2.1.0",
    session_id="purchase_flow_789"
)
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": "customer_456",
  "interaction_data_list": [
    {
      "role": "User",
      "content": "I need help choosing a laptop"
    },
    {
      "role": "Agent",
      "content": "I'd be happy to help! What's your budget?"
    },
    {
      "role": "User",
      "content": "Around $1000 for programming work"
    },
    {
      "role": "Agent",
      "content": "For programming, I recommend the ThinkPad X1..."
    }
  ],
  "source": "support-agent:v2",
  "agent_version": "v2.1.0",
  "session_id": "purchase_flow_789"
}
JSON

Example 4: Image Interactions

import base64

def encode_image(path):
    with open(path, "rb") as f:
        return base64.b64encode(f.read()).decode("utf-8")

# User shares an image
client.publish_interaction(
    user_id="user_123",
    interactions=[
        {
            "role": "User",
            "content": "What do you think of this outfit?",
            "image_encoding": encode_image("outfit.jpg")
        },
        {
            "role": "Agent",
            "content": "Great choice! The colors complement each other well."
        }
    ],
    source="styling_consultation",
    session_id="style_session_001"
)
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": "What do you think of this outfit?",
      "image_encoding": "<encode_image_result>"
    },
    {
      "role": "Agent",
      "content": "Great choice! The colors complement each other well."
    }
  ],
  "source": "styling_consultation",
  "session_id": "style_session_001"
}
JSON

Example 5: Expert Content for Learning from Experts

# Provide expert ideal responses for playbook extraction
client.publish_interaction(
    user_id="user_123",
    interactions=[
        {"role": "User", "content": "What is your return policy for electronics?"},
        {
            "role": "Agent",
            "content": "You can return electronics within 30 days.",
            "expert_content": (
                "Electronics can be returned within 30 days with the original receipt. "
                "Items must be in original packaging. Opened software is final sale. "
                "Defective items have a 90-day return window."
            )
        }
    ],
    source="expert_review",
    agent_version="v1.0",
    session_id="expert_session_001"
)
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": "What is your return policy for electronics?"
    },
    {
      "role": "Agent",
      "content": "You can return electronics within 30 days.",
      "expert_content": "Electronics can be returned within 30 days with the original receipt. Items must be in original packaging. Opened software is final sale. Defective items have a 90-day return window."
    }
  ],
  "source": "expert_review",
  "agent_version": "v1.0",
  "session_id": "expert_session_001"
}
JSON

Example 6: User Action Tracking

# Track user behavior on your platform
client.publish_interaction(
    user_id="shopper_789",
    interactions=[
        {
            "user_action": "click",
            "user_action_description": "Clicked 'Add to Cart' for MacBook Pro",
            "interacted_image_url": "https://store.com/products/macbook-pro.jpg"
        },
        {
            "user_action": "scroll",
            "user_action_description": "Scrolled through laptop accessories"
        }
    ],
    source="ecommerce",
    session_id="shopping_session_001"
)
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": "shopper_789",
  "interaction_data_list": [
    {
      "user_action": "click",
      "user_action_description": "Clicked 'Add to Cart' for MacBook Pro",
      "interacted_image_url": "https://store.com/products/macbook-pro.jpg"
    },
    {
      "user_action": "scroll",
      "user_action_description": "Scrolled through laptop accessories"
    }
  ],
  "source": "ecommerce",
  "session_id": "shopping_session_001"
}
JSON

search_interactions

Search for user interactions using semantic queries.

response = client.search_interactions(
    user_id="user_123",
    query="laptop recommendations",
    top_k=5,
    most_recent_k=10
)
curl -X POST "${REFLEXIO_URL:-https://www.reflexio.ai}/api/search_interactions" \
  -H "User-Agent: my-agent-reflexio" \
  -H "Authorization: Bearer $REFLEXIO_API_KEY" \
  -H "Content-Type: application/json" \
  --data @- <<'JSON'
{
  "user_id": "user_123",
  "query": "laptop recommendations",
  "top_k": 5,
  "most_recent_k": 10
}
JSON

Prop

Type

get_interactions

Retrieve user interactions without semantic search.

response = client.get_interactions(
    user_id="user_123",
    top_k=50
)
curl -X POST "${REFLEXIO_URL:-https://www.reflexio.ai}/api/get_interactions" \
  -H "User-Agent: my-agent-reflexio" \
  -H "Authorization: Bearer $REFLEXIO_API_KEY" \
  -H "Content-Type: application/json" \
  --data @- <<'JSON'
{
  "user_id": "user_123",
  "top_k": 50
}
JSON

Prop

Type

get_all_interactions

Get all user interactions across all users (admin operation).

response = client.get_all_interactions(limit=100)
curl -X GET "${REFLEXIO_URL:-https://www.reflexio.ai}/api/get_all_interactions?limit=100" \
  -H "User-Agent: my-agent-reflexio" \
  -H "Authorization: Bearer $REFLEXIO_API_KEY"

Prop

Type

Returns: GetInteractionsViewResponse with interactions from all users.

get_learning_status

Poll the learning status for a previously published request. Call this after a deferred publish_interaction (where wait_for_response=False). The response from the deferred path carries learning_status="deferred" to signal that extraction has been queued; use this method to track progress.

status = client.get_learning_status(request_id="req_abc123")
# Returns one of: "pending", "processing", "done", "failed"
curl -X GET "${REFLEXIO_URL:-https://www.reflexio.ai}/api/learning_status?request_id=req_abc123" \
  -H "User-Agent: my-agent-reflexio" \
  -H "Authorization: Bearer $REFLEXIO_API_KEY"

Prop

Type

Returns: str — one of "pending" | "processing" | "done" | "failed".

Status values:

ValueMeaning
pendingExtraction queued but not yet started
processingA durable-queue worker is currently processing this request
doneExtraction completed successfully
failedExtraction failed permanently (dead job)

Note: This endpoint reads learning_jobs rows written by the durable queue. When the durable queue is off (in-memory deferred path), status is absence-based: "pending" for recent requests, "done" for requests older than 72 hours.

Example: Publish and poll until done

import time

response = client.publish_interaction(
    user_id="user_123",
    interactions=[{"role": "User", "content": "Help me with X"}],
    session_id="sess_001",
    wait_for_response=False,
)
# response.learning_status == "deferred"

# The deferred response carries a request_id directly — no need to make a
# throwaway wait_for_response=True call first.
request_id = response.request_id

for _ in range(30):  # poll up to 30 seconds
    status = client.get_learning_status(request_id)
    if status in ("done", "failed"):
        print(f"Learning {status}")
        break
    time.sleep(1)

delete_interaction

Delete a specific user interaction.

response = client.delete_interaction(
    user_id,
    interaction_id,
    wait_for_response=False
)
curl -X DELETE "${REFLEXIO_URL:-https://www.reflexio.ai}/api/delete_interaction" \
  -H "User-Agent: my-agent-reflexio" \
  -H "Authorization: Bearer $REFLEXIO_API_KEY" \
  -H "Content-Type: application/json" \
  --data @- <<'JSON'
{
  "user_id": "<user_id>",
  "interaction_id": "<interaction_id>"
}
JSON

Prop

Type