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.

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,
)
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
}
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

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.

Evaluation-Only Publish

Set evaluation_only=True when the session should be graded but should not teach Reflexio new profiles or playbooks. In source-set comparisons, use this for the no-Reflexio baseline arm: publish the baseline transcript with a baseline source, then compare it against Reflexio-enabled sessions that use a test source.

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 evaluation if the session passes agent_success_config.sampling_rate, and excludes the request from profile extraction, playbook extraction, reflection, and aggregation. It does not bypass the session inactivity delay, and it is not a source-set grouping dimension; use source for cohorts such as prod_without_reflexio and prod_with_reflexio.

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="chat",
    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": "chat",
  "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="chat",
)
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": "chat"
}
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="sales_chat",
    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": "sales_chat",
  "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