OpenAI SDK

Setup

export XENOVIA_API_KEY=xe_...
export XENOVIA_AGENT_ID=your-agent-id

Python
Node.js

pip install openai

import os
from openai import OpenAI

client = OpenAI(
    api_key=os.environ["XENOVIA_API_KEY"],
    base_url=f"https://runtime.xenovia.io/{os.environ['XENOVIA_AGENT_ID']}/v1"
)

response = client.chat.completions.create(
    model="gpt-4o-mini",
    messages=[{"role": "user", "content": "Hello"}]
)
print(response.choices[0].message.content)

npm install openai

import OpenAI from "openai"

const client = new OpenAI({
  apiKey: process.env.XENOVIA_API_KEY,
  baseURL: `https://runtime.xenovia.io/${process.env.XENOVIA_AGENT_ID}/v1`
})

const response = await client.chat.completions.create({
  model: "gpt-4o-mini",
  messages: [{ role: "user", content: "Hello" }]
})
console.log(response.choices[0].message.content)

Streaming

Streaming works without any additional configuration. The runtime stamps X-Xenovia-Session-Id and X-Xenovia-Trace-Id into the response headers before the first byte.

Python
Node.js

stream = client.chat.completions.create(
    model="gpt-4o-mini",
    messages=[{"role": "user", "content": "Count to 5"}],
    stream=True
)
for chunk in stream:
    print(chunk.choices[0].delta.content or "", end="")

const stream = await client.chat.completions.create({
  model: "gpt-4o-mini",
  messages: [{ role: "user", content: "Count to 5" }],
  stream: true
})
for await (const chunk of stream) {
  process.stdout.write(chunk.choices[0]?.delta?.content ?? "")
}

Tool calling

Tool definitions pass through unchanged. Xenovia records tool call names and arguments in the trace and evaluates them against your request-stage Rego policy before forwarding.

tools = [
    {
        "type": "function",
        "function": {
            "name": "get_weather",
            "description": "Get the current weather for a location",
            "parameters": {
                "type": "object",
                "properties": {
                    "location": {"type": "string"}
                },
                "required": ["location"]
            }
        }
    }
]

response = client.chat.completions.create(
    model="gpt-4o-mini",
    messages=[{"role": "user", "content": "What's the weather in London?"}],
    tools=tools
)

If a tool name matches a block rule in your Rego policy, the request returns 403 before reaching the upstream LLM.

Sessions

Pass X-Xenovia-Session-Id (a valid UUID) to group related calls into a session. During a simulation, forward the value Xenovia sent instead (see Forwarding the simulation session). All turns under that session ID appear together in Sessions with a per-session turn counter.

Python
Node.js

import uuid

client = OpenAI(
    api_key=os.environ["XENOVIA_API_KEY"],
    base_url=f"https://runtime.xenovia.io/{os.environ['XENOVIA_AGENT_ID']}/v1",
    default_headers={"X-Xenovia-Session-Id": str(uuid.uuid4())}
)

import { randomUUID } from "crypto"

const client = new OpenAI({
  apiKey: process.env.XENOVIA_API_KEY,
  baseURL: `https://runtime.xenovia.io/${process.env.XENOVIA_AGENT_ID}/v1`,
  defaultHeaders: { "X-Xenovia-Session-Id": randomUUID() }
})

If you omit the header, Xenovia resolves a session automatically using message fingerprinting or the user field. See Runtime Architecture for the full five-strategy chain.

Forwarding the simulation session

Simulation sends your agent an X-Xenovia-Session-Id header with every turn. Pass it, unchanged, on each model call made for that turn, so Xenovia can grade a scenario’s tool and instruction-leak checks and apply the run’s provider and mode. On the Xenovia cloud runtime it is a signed value (xsim1.…), not a UUID; don’t parse, trim or replace it, because a changed value is rejected with 400.

Python
Node.js

session = request.headers.get("X-Xenovia-Session-Id")
response = client.chat.completions.create(
    model="gpt-4o-mini",
    messages=messages,
    extra_headers={"X-Xenovia-Session-Id": session} if session else {}
)

const session = req.get("X-Xenovia-Session-Id")
const response = await client.chat.completions.create(
  { model: "gpt-4o-mini", messages },
  { headers: session ? { "X-Xenovia-Session-Id": session } : {} }
)

Pass it per call, not in default_headers on a shared client: a fixed header sends the same session on every request, so concurrent conversations would be merged into one session and graded together.

Custom trace properties

Attach up to 20 X-Xenovia-Property-* headers to tag traces with application context. Keys must be ≤ 64 chars; values ≤ 512 chars; the policy_ prefix is reserved.

client = OpenAI(
    api_key=os.environ["XENOVIA_API_KEY"],
    base_url=f"https://runtime.xenovia.io/{os.environ['XENOVIA_AGENT_ID']}/v1",
    default_headers={
        "X-Xenovia-Session-Id": str(uuid.uuid4()),
        "X-Xenovia-Property-user-tier": "enterprise",
        "X-Xenovia-Property-feature": "document-summary"
    }
)

Policy blocks

When a request is blocked by policy, the runtime returns 403 Forbidden. The OpenAI SDK raises this as PermissionDeniedError. The X-Xenovia-Trace-Id response header identifies the blocking trace.

Python
Node.js

from openai import PermissionDeniedError

try:
    response = client.chat.completions.create(
        model="gpt-4o-mini",
        messages=[{"role": "user", "content": "Delete everything"}],
        tools=tools
    )
except PermissionDeniedError as e:
    print(f"Blocked by policy: {e.message}")

import { PermissionDeniedError } from "openai"

try {
  const response = await client.chat.completions.create({
    model: "gpt-4o-mini",
    messages: [{ role: "user", content: "Delete everything" }],
    tools
  })
} catch (e) {
  if (e instanceof PermissionDeniedError) {
    console.log("Blocked by policy:", e.message)
  }
}

Reading trace headers

The response always includes trace headers you can log for correlation:

import httpx
from openai import OpenAI

# Use httpx to access response headers
with httpx.Client() as http:
    resp = http.post(
        f"https://runtime.xenovia.io/{os.environ['XENOVIA_AGENT_ID']}/v1/chat/completions",
        headers={
            "Authorization": f"Bearer {os.environ['XENOVIA_API_KEY']}",
            "Content-Type": "application/json"
        },
        json={
            "model": "gpt-4o-mini",
            "messages": [{"role": "user", "content": "Hello"}]
        }
    )
    trace_id = resp.headers.get("X-Xenovia-Trace-Id")
    session_id = resp.headers.get("X-Xenovia-Session-Id")
    print(f"Trace: {trace_id}, Session: {session_id}")

Start Here

Integrations

Platform

Setup

Streaming

Tool calling

Sessions

Forwarding the simulation session

Custom trace properties

Policy blocks

Reading trace headers

​Setup

​Streaming

​Tool calling

​Sessions

​Forwarding the simulation session

​Custom trace properties

​Policy blocks

​Reading trace headers

Setup

Streaming

Tool calling

Sessions

Forwarding the simulation session

Custom trace properties

Policy blocks

Reading trace headers