Skip to main content
The detail behind the Quickstart and Hooks.

Constructor parameters

Do not set agent_role. The runtime no longer accepts it: every check from a client with agent_role set fails with 400 (agent_role is no longer supported: use a sub-agent key), raised as XenoviaExecutionError. Use a sub-agent key instead. The agent_depth field in the request body is accepted but ignored; the runtime reads the depth from the x-xenovia-agent-depth header instead, which the SDK does not set.
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

The decision never contains the rule or the reason. Look up trace_id in the platform to see which policy or guardrail fired.

Sessions

The runtime issues the session and returns it in the X-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_id holds 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 with X-Xenovia-Session-Id. A UUID the runtime has not seen fails with 403 (unknown session), and another agent’s session fails with 403 (session ownership mismatch). Both raise XenoviaExecutionError.
  • To group SDK checks with model turns, send the model call first with your own X-Xenovia-Session-Id, then pass the same ID as session_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 with 400 (unknown session turn). Without turn=, each check gets its own trace.
  • next_turn() only advances a local counter.
Inside a request handled by the session middleware, 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 the X-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

A 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 Authorization header, never in payloads or logs.
  • Debug output prints the operation, decision outcome, and trace ID, not payloads.