Traces and Remediation

Every request to an agent and every SDK check that passes validation and authentication produces a turn record, grouped under a session. Turns carry the model and tool runs, token counts, latency, and the policy and guardrail decisions. The Sessions page lists them.

What a turn records

Field	Description
`trace_id`	Identifier for this turn
`session_id`	The session this turn belongs to
`turn_number`	Position within the session
`agent_id` / `org_id`	Agent and organization
`provider`	Resolved upstream provider
`model`	Model the runtime called
`request_type`	`chat_completion`, `chat_completion_stream`, `responses`, or `responses_stream`
`status`	`allowed`, `blocked`, `escalated`, or `error`
`tokens_in` / `tokens_out`	Prompt and completion tokens
`latency_ms`	Total latency
`ttft_ms`	Time to first token (streaming)
`policy_decision` / `policy_rule`	Final policy action and the rule that fired
`custom_properties`	Key–value pairs from `X-Xenovia-Property-*` headers

Inside a turn, each unit of work is a run: the model call, plus policy and runtime-executed tool runs. Client-executed tool calls appear in the turn’s output.tool_calls and, once returned, in the next turn’s tool_results.

Enriching a turn

Attach these headers to any request to the agent endpoint:

client = OpenAI(
    api_key=os.environ["XENOVIA_API_KEY"],
    base_url=f"https://runtime.xenovia.io/{os.environ['XENOVIA_AGENT_ID']}/v1",
    default_headers={
        # Group related calls under one session (a valid UUID)
        "X-Xenovia-Session-Id": "550e8400-e29b-41d4-a716-446655440000",
        # Tag the turn with business context
        "X-Xenovia-Property-user-tier": "enterprise",
        "X-Xenovia-Property-feature": "document-summary",
    }
)

Custom property rules:

At most 20 properties per request; extras are dropped silently.
Property names are lowercased; keep them to 64 characters or fewer.
Values are truncated to 512 bytes.
Names beginning policy_ are reserved and dropped.
A property that breaks a rule is skipped without an error, so confirm important tags appear on the trace.

For cross-request linkage, X-Xenovia-Parent-Trace-Id sets a parent run and X-Xenovia-Trace-Flow-Id groups turns into a flow.

X-Xenovia-Session-Path is not currently read by the runtime. Use X-Xenovia-Session-Id for grouping and X-Xenovia-Property-* for filtering.

Response headers

Every response includes:

Header	Value
`X-Xenovia-Session-Id`	Resolved session UUID
`X-Xenovia-Trace-Id`	Per-request trace UUID

Use X-Xenovia-Trace-Id to find a specific call in the platform. A malformed X-Xenovia-Session-Id request header is rejected with 400.

Investigating

Notice

Watch the Sessions and Alerts views for a rise in blocks or a spike in escalations. Configure alert rules to be told rather than to poll.

Drill in

Open a session and read its turns. Each turn carries the messages, tools, model, tokens, decision, and custom properties, so the cause is visible without stitching logs together.

Adjust

Update the Rego policy or guardrail, or revoke an agent key. Configuration changes reach the runtime within about five minutes.

Confirm

Send the request again and check the new turn. Historical turns are immutable, so earlier decisions remain as evidence after a change.

Escalations are queued on the session and surface in Alerts. Resolving one records the reviewer’s note; it does not replay or release the original request.

Querying traces programmatically

The management API exposes sessions, turns, aggregate stats, escalations, and multi-agent workflows. The GET /api/v1/traces endpoint filters by agent (agent_id), session, decision, provider, and time range, and by any custom property as cp_<key>=<value>.

Start Here

Integrations

Platform

Traces and Remediation

What a turn records

Enriching a turn

Response headers

Investigating

Querying traces programmatically

​What a turn records

​Enriching a turn

​Response headers

​Investigating

​Querying traces programmatically

What a turn records

Enriching a turn

Response headers

Investigating

Querying traces programmatically