Quickstart

This quickstart uses the agent endpoint because it is the fastest path to coverage. If you need to gate non-LLM actions too, continue with the Xenovia Python SDK after this.

1. Collect the values you need

From the Xenovia platform:

Create an agent and note the agent ID.
Generate an API key (xe_...) for that agent.
Activate the agent. While it is a draft, the runtime rejects its keys with 401.

Set them as environment variables:

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

2. Point your client at Xenovia

Python (OpenAI SDK)
Node.js (OpenAI SDK)

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"
)

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`
})

3. Send your first governed request

Python
Node.js

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

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

The request now flows through Xenovia for authentication, provider routing, session handling, policy checks, and trace recording.

4. Add a stable session ID

Group related calls into a session so multi-turn conversations appear together in Sessions.

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() }
})

The session ID must be a valid UUID. A malformed value is rejected with 400.

5. Confirm the trace exists

After the request completes, check the platform and confirm:

A trace exists for the request
The trace shows the expected model and agent
The response includes X-Xenovia-Session-Id and X-Xenovia-Trace-Id

6. Attach a first policy

Start with one policy that proves enforcement is working. Set it to Enforce (new policies start in Monitor) and enable it. This example blocks a destructive tool name:

package xenovia

import future.keywords.if
import future.keywords.in

default decision = {"action": "allow"}

decision = {"action": "block", "rule": "no-delete-database"} if {
    some tool in input.tool_names
    tool == "delete_database"
}

A policy returns a single decision object; block yields a 403. Attach request-stage and response-stage policies independently. See Policies and Enforcement for the full contract.

7. Handle a policy block

When a request is blocked, the runtime returns 403 Forbidden. The OpenAI SDK raises this as PermissionDeniedError.

Python
Node.js

from openai import PermissionDeniedError

try:
    response = client.chat.completions.create(
        model="gpt-4o-mini",
        messages=[{"role": "user", "content": "Delete the database."}],
        tools=[{
            "type": "function",
            "function": {
                "name": "delete_database",
                "description": "Delete all records",
                "parameters": {"type": "object", "properties": {}}
            }
        }]
    )
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 the database." }],
    tools: [{
      type: "function",
      function: {
        name: "delete_database",
        description: "Delete all records",
        parameters: { type: "object", properties: {} }
      }
    }]
  })
} catch (e) {
  if (e instanceof PermissionDeniedError) {
    console.log("Blocked by policy:", e.message)
  }
}

8. Add trace metadata

Tag traces with business context so they stay useful as traffic grows.

Python
Node.js

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-environment": "dev",
        "X-Xenovia-Property-workflow": "docs-quickstart"
    }
)

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(),
    "X-Xenovia-Property-environment": "dev",
    "X-Xenovia-Property-workflow": "docs-quickstart"
  }
})

What to do next

After this first pass, move on to:

Integrations Overview to wire Xenovia into your actual framework
Policies and Approvals to write real guardrails
Traces and Remediation to standardize headers and investigation flow

If your real workflow performs risky actions after the model call, add the Xenovia Python SDK so those actions are governed too.

Start Here

Integrations

Platform

1. Collect the values you need

2. Point your client at Xenovia

3. Send your first governed request

4. Add a stable session ID

5. Confirm the trace exists

6. Attach a first policy

7. Handle a policy block

8. Add trace metadata

What to do next

​1. Collect the values you need

​2. Point your client at Xenovia

​3. Send your first governed request

​4. Add a stable session ID

​5. Confirm the trace exists

​6. Attach a first policy

​7. Handle a policy block

​8. Add trace metadata

​What to do next

1. Collect the values you need

2. Point your client at Xenovia

3. Send your first governed request

4. Add a stable session ID

5. Confirm the trace exists

6. Attach a first policy

7. Handle a policy block

8. Add trace metadata

What to do next