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.
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
- OpenAI SDK
- Anthropic SDK
- LangChain
- LlamaIndex
- OpenAI Agents SDK
- Vercel AI SDK
- AutoGen and CrewAI
The best default for any OpenAI-compatible client, in Python or Node.js.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.A streamed request gets the same refusal as a stream that ends with
Streaming
Streaming works without any additional configuration.Tool calling
Tool definitions pass through unchanged. The request-stage policy sees the offered tool names ininput.tool_names before the model is called. The tool calls the model returns are checked at the response stage, before your code receives them.Handling a block
A block is a200 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: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.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 answers200 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
PassX-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 setsX-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 20X-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.