Constructor parameters
unreachable_mode values:
The
"block" and "allow" fallbacks are produced by the SDK on your machine, not by Xenovia. You can tell them apart from a real decision: decision["rule_id"] is SDK_UNREACHABLE_BLOCK or SDK_UNREACHABLE_ALLOW, trace_id is None, and no trace appears in the platform.XenoviaResponse
trace_id in the platform to see which policy or guardrail fired.
Sessions
The runtime issues the session and returns it in theX-Xenovia-Session-Id response header; the SDK reads it into response.session_id.
- With
auto_session=True, the first call lets the runtime create a session, and later calls reuse it.xenovia.session_idholds it after the first decision. - To pass
session_id=yourself, use a session the runtime already knows: one an earlier SDK call returned, or one your agent endpoint traffic created withX-Xenovia-Session-Id. A UUID the runtime has not seen fails with403(unknown session), and another agent’s session fails with403(session ownership mismatch). Both raiseXenoviaExecutionError. - To group SDK checks with model turns, send the model call first with your own
X-Xenovia-Session-Id, then pass the same ID assession_id=. - Sessions expire after 30 minutes without activity.
- If the runtime returns a different session than the one you sent, the SDK raises
XenoviaExecutionError. turn=attaches a check to a turn your agent endpoint traffic started in that session. It needs a session, and a turn the session has not reached fails with400(unknown session turn). Withoutturn=, each check gets its own trace.next_turn()only advances a local counter.
execute() and every hook send that request’s session when you pass no session_id=. That session is not stored as the client’s automatic session.
Route model calls through Xenovia
The SDK includes helpers that point an OpenAI-compatible client at the agent endpoint and forward theX-Xenovia-Session-Id header of the request your agent is handling. When whatever calls your agent sends that header, the agent’s model calls and SDK checks join the caller’s session.
openai_client_kwargs() reads XENOVIA_RUNTIME_URL (default https://runtime.xenovia.io), XENOVIA_AGENT_ID, and XENOVIA_API_KEY unless you pass runtime_url=, agent_id=, or api_key=. It builds a new httpx client on each call, so create your model client once and reuse it. The session header is added only when a session is set, and its value is forwarded unchanged, so it must be a UUID for the runtime to accept it.
Error handling
XenoviaExecutionError from an HTTP error names the status, the runtime’s error text, and the trace ID when there is one. Malformed input raises ValueError before any request is sent, for example a model_pre message part the SDK cannot read.
Wire format
session_id and turn are sent only when set. The runtime reads stage, operation, payload, session_id, and turn; identity, env, and sdk are informational. The response body is {"status", "decision": {"outcome", "escalated"}, "payload", "trace_id"}, with the session in the X-Xenovia-Session-Id header. A denial is 403 with status: "blocked" and no reason.
Security
- HTTPS is required unless
allow_insecure_http=True, which is limited to loopback addresses. - The API key is sent only in the
Authorizationheader, never in payloads or logs. - Debug output prints the operation, decision outcome, and trace ID, not payloads.