Skip to main content

Documentation Index

Fetch the complete documentation index at: https://docs.xenovia.io/llms.txt

Use this file to discover all available pages before exploring further.

​
What a trace contains

Every proxied request produces a structured trace with the following fields:
FieldDescription
trace_idUnique UUID for this request
session_idSession UUID resolved for this call
session_turnTurn number within the session (atomic counter)
session_pathHierarchical path label from X-Xenovia-Session-Path
proxy_idProxy identity
org_idOrganisation identity
providerUpstream provider used
modelModel name
request_typechat_completions, responses, embeddings, completions
messagesRequest messages (truncated)
toolsTool schemas requested
response_contentLLM response content (truncated)
tokens_inPrompt token count
tokens_outCompletion token count
latency_msTotal request latency
ttft_msTime to first token (streaming only)
policy_outcomeallow, block, redact, block_response, redact_response
policy_rule_idRule identifier from the Rego policy
policy_reasonHuman-readable reason string
intent_scoreSemantic similarity score (0.0–1.0)
intent_actionallow, block, escalate
custom_propertiesKey-value pairs from X-Xenovia-Property-* headers
parent_trace_idParent trace UUID (for linked requests)
flow_idFlow grouping UUID from X-Xenovia-Trace-Flow-Id
Tool call traces are child steps under the parent trace:
FieldDescription
step_typetool_call or tool_result
tool_nameFunction name
tool_argsArgument object
tool_resultReturn value
call_idModel-assigned tool call ID
statussuccess or error
latency_msCall-to-result latency

​
Request headers for trace enrichment

Attach these headers to any proxied request to enrich the trace: 
client = OpenAI(
    api_key=os.environ["XENOVIA_API_KEY"],
    base_url=f"https://runtime.xenovia.io/a/{os.environ['XENOVIA_PROXY_ID']}/openai/v1",
    default_headers={
        # Group all calls in this workflow under one session
        "X-Xenovia-Session-Id": "550e8400-e29b-41d4-a716-446655440000",
        # Tag this session with a path for hierarchical filtering
        "X-Xenovia-Session-Path": "onboarding/step-3",
        # Link to a parent trace from a different system
        "X-Xenovia-Parent-Trace-Id": "parent-trace-uuid",
        # Group multiple sessions into one flow
        "X-Xenovia-Trace-Flow-Id": "flow-uuid",
        # Custom properties (up to 20 per request)
        "X-Xenovia-Property-user-tier": "enterprise",
        "X-Xenovia-Property-feature-flag": "v2-agent",
    }
)
Custom property constraints:
  • Maximum 20 properties per request.
  • Key length ≤ 64 characters.
  • Value length ≤ 512 characters.
  • The policy_ key prefix is reserved for internal use.

​
Response headers

Every response includes:
HeaderValue
X-Xenovia-Session-IdResolved session UUID
X-Xenovia-Trace-IdPer-request trace UUID
Use X-Xenovia-Trace-Id to correlate a specific call with its trace in the platform.

​
Trace step flow

Xenovia emits trace steps as a request progresses: 
request_received → [policy step] → [intent step] → llm → [escalation step] → [tool steps] → request_finished
Each step is a child trace with its own UUID, linked via parent_trace_id. This allows filtering the full lifecycle of a single request.

​
Drift detection and remediation

When agent behaviour drifts from expected patterns:
1

Detect

Policy blocks increase, intent scores drop, or escalation volume spikes. The platform surfaces these as aggregate signals over sessions and proxies.
2

Investigate

Drill into traces filtered by session, policy outcome, or intent action. Each trace includes the full request context — messages, tools, model, session turn, and custom properties — so the cause is visible without reconstructing state from separate logs.
3

Decide

Approve a pending escalation, update the Rego policy, adjust the intent definition, or revoke a proxy key. Changes take effect within the 5-minute Redis cache TTL.
4

Remediate

Apply the fix. Historical traces are immutable — prior decisions remain intact as evidence even after a policy update. This preserves audit continuity.
5

Tune

Use trace data to refine policy rules. Avoid over-blocking by reviewing traces where intent_score is borderline or policy_outcome is redact.

​
Response readiness checklist

  • Incident owners mapped per critical proxy.
  • Escalation thresholds set in the intent configuration.
  • Trace retention period meets compliance requirements.
  • X-Xenovia-Property-* headers used to tag requests with environment, user tier, or feature context.
  • Post-incident policy updates are committed with a change reason for audit trail.