Skip to main content
Keep your prompts, tools and framework. Change the base URL to your agent’s and use its key, and every model call is checked and recorded before it reaches the model. For example, an OpenAI client:

The change

Every agent has an endpoint on the Xenovia runtime. It speaks two APIs: The agent’s page shows its exact base URL under Setup; the agent ID is the part between the host and /v1. Create the key on the agent’s API keys tab (see Create an agent). An agent that runs on a hybrid deployment uses its deployment’s URL instead of runtime.xenovia.io.
Provider credentials are configured on the agent and resolved server-side. So is the model: the model field in your request is ignored, and every request goes to the model set on the agent’s provider. Either API works whichever provider the agent routes to. To change models, update the agent, not your code. Other provider-native SDKs, such as the Gemini, Bedrock or Groq clients, use API paths the runtime does not serve, so their requests return 404. Use an OpenAI-compatible client for those agents.

Pick your client

The best default for any OpenAI-compatible client, in Python or Node.js.

Streaming

Streaming works without any additional configuration.

Tool calling

Tool definitions pass through unchanged. The request-stage policy sees the offered tool names in input.tool_names before the model is called. The tool calls the model returns are checked at the response stage, before your code receives them.
If a tool name matches a block rule in your request-stage policy, the model is not called and the runtime answers with a refusal. If a tool call in the reply is blocked, the runtime asks the model once more without it, and you receive the model’s new answer, or the refusal if that is blocked too.

Handling a block

A block is a 200 refusal: finish_reason is "content_filter", and I can't help with that request. is both message.content and message.refusal. Use the raw-response accessor to read the headers:
A streamed request gets the same refusal as a stream that ends with finish_reason: "content_filter". The OpenAI SDK’s typed errors still apply to real failures. A 403 (PermissionDeniedError) means the agent is not active, or the session belongs to another organization. It never means a policy block.
If your framework isn’t listed: if it accepts an OpenAI-compatible base_url, start from the OpenAI SDK tab; if it uses the Anthropic SDK, start from the Anthropic tab; if it only needs HTTP, point it at https://runtime.xenovia.io/{agent_id}/v1.

What every client gets

Blocks are replies, not errors

When a policy or Neon blocks a call, or a policy escalates it, the runtime answers 200 with a refusal in the format of the API you called: Chat Completions returns finish_reason: "content_filter", Responses returns status: "incomplete", and Messages returns stop_reason: "refusal". The X-Xenovia-Decision: blocked header marks it, so check that header rather than catching exceptions. If a blocked reply or tool call was sent back to the model once, X-Xenovia-Retried: true marks the answer. See What a block looks like to your app.

Sessions

Pass X-Xenovia-Session-Id to group related calls into a session. The value must be a UUID; anything else returns 400. All turns under that ID appear together in Sessions with a per-session turn counter. If you omit the header, Xenovia resolves a session from the previous_response_id, the user field or the conversation (see Runtime).

Streaming

The runtime sets X-Xenovia-Session-Id and X-Xenovia-Trace-Id in the response headers before the first byte. A stream is sent live, chunk by chunk, only when nothing the agent enforces could act on the reply. Otherwise the runtime waits for the complete reply, checks it, and replays it as a stream, so the whole reply arrives at once. The X-Xenovia-Stream-Mode response header says live or buffered. Streams from /v1/responses are always buffered.

Trace properties

Attach up to 20 X-Xenovia-Property-* headers to tag traces with application context, such as X-Xenovia-Property-feature: document-summary. See Enriching a turn for the rules.

Response headers

Paths the runtime serves

Embeddings (/v1/embeddings), legacy completions (/v1/completions) and model listing (/v1/models) are not exposed by the runtime today and return 404. Send embedding calls directly to your provider until they are supported.

Check what your code does, too

The endpoint checks model traffic. To check the actions your code takes around it, such as tool calls and their results, memory writes and context summaries, add the Xenovia SDK.

What next?

Add a policy

Block one thing your agent should never do.

Read a session

See each call, check and decision.

Split an agent into steps

Give one step its own key and checks.