> ## Documentation Index
> Fetch the complete documentation index at: https://docs.xenovia.io/llms.txt
> Use this file to discover all available pages before exploring further.

# Connect your app

> Point the model client you already use at your agent: one base URL and one key.

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:

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

## The change

Every agent has an endpoint on the Xenovia runtime. It speaks two APIs:

| Client | Base URL | Key |
| - | - | - |
| OpenAI-compatible clients | `https://runtime.xenovia.io/{agent_id}/v1` | The agent's `xe_` key as the client's API key |
| Anthropic SDKs | `https://runtime.xenovia.io/{agent_id}` (no `/v1`) | The agent's `xe_` key as the client's API key |

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](https://docs.xenovia.io/agents/create-an-agent.md)). An agent that runs on a [hybrid deployment](https://docs.xenovia.io/organization/hybrid.md) uses its deployment's URL instead of `runtime.xenovia.io`.

```bash theme={null}
export XENOVIA_API_KEY=xe_...
export XENOVIA_AGENT_ID=your-agent-id
```

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](https://docs.xenovia.io/providers/overview.md) 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

> [tab] OpenAI SDK
>
> The best default for any OpenAI-compatible client, in Python or Node.js.
>
> ```python Python theme={null}
> # 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",  # ignored: the agent's configured model is used
>     messages=[{"role": "user", "content": "Hello"}]
> )
> print(response.choices[0].message.content)
> ```
>
> ```typescript Node.js theme={null}
> // 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", // ignored: the agent's configured model is used
>   messages: [{ role: "user", content: "Hello" }]
> })
> console.log(response.choices[0].message.content)
> ```
>
> ### Streaming
>
> Streaming works without any additional configuration.
>
> ```python Python theme={null}
> stream = client.chat.completions.create(
>     model="gpt-4o-mini",
>     messages=[{"role": "user", "content": "Count to 5"}],
>     stream=True
> )
> for chunk in stream:
>     if chunk.choices:
>         print(chunk.choices[0].delta.content or "", end="")
> ```
>
> ```typescript Node.js theme={null}
> 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. 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.
>
> ```python theme={null}
> 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 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:
>
> ```python Python theme={null}
> raw = client.chat.completions.with_raw_response.create(
>     model="gpt-4o-mini",
>     messages=[{"role": "user", "content": "Delete everything"}],
>     tools=tools
> )
> response = raw.parse()
>
> if raw.headers.get("X-Xenovia-Decision") == "blocked":
>     print(f"Blocked by policy. Trace: {raw.headers.get('X-Xenovia-Trace-Id')}")
> else:
>     print(response.choices[0].message.content)
> ```
>
> ```typescript Node.js theme={null}
> const { data, response } = await client.chat.completions
>   .create({
>     model: "gpt-4o-mini",
>     messages: [{ role: "user", content: "Delete everything" }],
>     tools
>   })
>   .withResponse()
>
> if (response.headers.get("x-xenovia-decision") === "blocked") {
>   console.log("Blocked by policy. Trace:", response.headers.get("x-xenovia-trace-id"))
> } else {
>   console.log(data.choices[0].message.content)
> }
> ```
>
> 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.

> [tab] Anthropic SDK
>
> The runtime serves Anthropic's Messages API, so the Anthropic SDKs connect with a base URL and the agent's `xe_` key. The base URL is the agent's root, with no `/v1`: the SDKs add `/v1/messages` themselves.
>
> ```python Python theme={null}
> # pip install anthropic
> import os
> import anthropic
>
> client = anthropic.Anthropic(
>     api_key=os.environ["XENOVIA_API_KEY"],
>     base_url=f"https://runtime.xenovia.io/{os.environ['XENOVIA_AGENT_ID']}"
> )
>
> message = client.messages.create(
>     model="claude-sonnet-4-5",  # ignored: the agent's configured model is used
>     max_tokens=1024,
>     messages=[{"role": "user", "content": "Hello"}]
> )
> print(message.content[0].text)
> ```
>
> ```typescript TypeScript theme={null}
> // npm install @anthropic-ai/sdk
> import Anthropic from "@anthropic-ai/sdk"
>
> const client = new Anthropic({
>   apiKey: process.env.XENOVIA_API_KEY,
>   baseURL: `https://runtime.xenovia.io/${process.env.XENOVIA_AGENT_ID}`
> })
>
> const message = await client.messages.create({
>   model: "claude-sonnet-4-5", // ignored: the agent's configured model is used
>   max_tokens: 1024,
>   messages: [{ role: "user", content: "Hello" }]
> })
> console.log(message.content)
> ```
>
> The runtime reads the `xe_` key from `x-api-key` or `Authorization: Bearer`, so the SDK's `api_key` (or `auth_token`) works whichever header your SDK version sends. The key authenticates you to Xenovia. The provider is called with the credential configured on the agent.
>
> ### Model and provider
>
> The runtime uses the model configured on the agent's provider, and removes any `fallbacks` you send. The Messages routes never run [fallback providers](https://docs.xenovia.io/providers/fallbacks.md): every request is served by the agent's primary provider.
>
> When the provider is not a Claude model, the request is translated:
>
> * Anthropic-only hints the provider cannot use, such as `cache_control` or `context_management`, are dropped. The `X-Xenovia-Dropped-Fields` response header names them.
> * Fields that would change the reply or where data is processed, such as `stop_sequences` or `inference_geo`, are refused with `400`. Some OpenAI-compatible servers, such as vLLM, receive `stop_sequences` as `stop` instead.
>
> On any provider, an `anthropic-beta` value the runtime does not support, or a Files API `file` source, is refused with `400`. Send file content inline.
>
> ### Token counting
>
> `count_tokens` is answered by the runtime with an estimate. The request is not sent to the provider, and no model call or billing event is recorded. The response carries `X-Xenovia-Token-Count: estimate`. Use the `usage` of the real call for exact counts. `stream` is ignored on `count_tokens`.
>
> ```python Python theme={null}
> count = client.messages.count_tokens(
>     model="claude-sonnet-4-5",
>     messages=[{"role": "user", "content": "Hello"}]
> )
> print(count.input_tokens)
> ```
>
> ```typescript TypeScript theme={null}
> const count = await client.messages.countTokens({
>   model: "claude-sonnet-4-5",
>   messages: [{ role: "user", content: "Hello" }]
> })
> console.log(count.input_tokens)
> ```
>
> ### Handling a block
>
> A block is a `200` refusal message: `stop_reason` is `"refusal"`, the content is one text block reading `I can't help with that request.`, and `stop_details` is `{"type": "refusal", "category": null, "explanation": "I can't help with that request."}`. Read the headers to tell a Xenovia block from the model's own refusal.
>
> ```python Python theme={null}
> raw = client.messages.with_raw_response.create(
>     model="claude-sonnet-4-5",
>     max_tokens=1024,
>     messages=[{"role": "user", "content": "Delete everything"}]
> )
> message = raw.parse()
>
> if raw.headers.get("X-Xenovia-Decision") == "blocked":
>     print(f"Blocked by policy. Trace: {raw.headers.get('X-Xenovia-Trace-Id')}")
> else:
>     print(message.content[0].text)
> ```
>
> ```typescript TypeScript theme={null}
> const { data, response } = await client.messages
>   .create({
>     model: "claude-sonnet-4-5",
>     max_tokens: 1024,
>     messages: [{ role: "user", content: "Delete everything" }]
>   })
>   .withResponse()
>
> if (response.headers.get("x-xenovia-decision") === "blocked") {
>   console.log("Blocked by policy. Trace:", response.headers.get("x-xenovia-trace-id"))
> } else {
>   console.log(data.content)
> }
> ```
>
> A streamed request gets the refusal as stream events. Errors on the Messages routes use Anthropic's error format, so the SDKs raise their usual typed exceptions. A `403` (`PermissionDeniedError`) means the agent is not active, or the session belongs to another organization. It never means a policy block.
>
> ### Claude Code and the Claude Agent SDK
>
> Claude Code and the Claude Agent SDK use the same routes. Set `ANTHROPIC_BASE_URL` to `https://runtime.xenovia.io/{agent_id}` and `ANTHROPIC_API_KEY` to the agent's `xe_` key. To govern what Claude Code does on a developer's machine, not only its model calls, see [Coding agents](https://docs.xenovia.io/agents/coding-agents.md).

> [tab] LangChain
>
> `ChatOpenAI` works for every Xenovia agent, whichever provider the agent routes to. `ChatAnthropic` works too, through the Messages API routes. The `model` argument is a placeholder that the runtime replaces with the agent's configured model, and the `model` field in the response reports the model that actually served the request.
>
> ### Setup
>
> The Python examples are checked with Python 3.12, `langchain` / `langchain-openai` 1.0.0 and `langchain` 1.4.0 / `langchain-openai` 1.6.1 using simulated HTTP responses. Validate your agent's policies, guardrails, and provider configuration separately.
>
> ```bash theme={null}
> pip install "langchain>=1,<2" "langchain-openai>=1,<2"
> export XENOVIA_API_KEY=xe_...
> export XENOVIA_AGENT_ID=your-agent-id
> ```
>
> ```python theme={null}
> import os
> import uuid
> from langchain_openai import ChatOpenAI
>
> session_id = str(uuid.uuid4())
>
> llm = ChatOpenAI(
>     model="gpt-4o-mini",  # placeholder: the agent's configured model is used
>     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": session_id},
>     include_response_headers=True  # exposes X-Xenovia-* headers on each reply
> )
> ```
>
> In Node.js:
>
> ```typescript theme={null}
> // npm install @langchain/openai
> import { ChatOpenAI } from "@langchain/openai"
>
> const llm = new ChatOpenAI({
>   model: "gpt-4o-mini", // placeholder: the agent's configured model is used
>   apiKey: process.env.XENOVIA_API_KEY,
>   configuration: {
>     baseURL: `https://runtime.xenovia.io/${process.env.XENOVIA_AGENT_ID}/v1`
>   }
> })
> ```
>
> ### One client for every provider
>
> The client you choose sets the API your code speaks, not the provider:
>
> | LangChain class | Base URL |
> | - | - |
> | `ChatOpenAI` | `https://runtime.xenovia.io/{agent_id}/v1` |
> | `ChatAnthropic` | `https://runtime.xenovia.io/{agent_id}` (no `/v1`) |
>
> For `ChatAnthropic`, install `langchain-anthropic`:
>
> ```python theme={null}
> from langchain_anthropic import ChatAnthropic
>
> claude = ChatAnthropic(
>     model="claude-sonnet-4-5",  # placeholder: the agent's configured model is used
>     api_key=os.environ["XENOVIA_API_KEY"],
>     base_url=f"https://runtime.xenovia.io/{os.environ['XENOVIA_AGENT_ID']}",
>     default_headers={"X-Xenovia-Session-Id": session_id}
> )
> ```
>
> Other provider-native classes, such as `ChatGroq`, `ChatBedrock` or `ChatGoogleGenerativeAI`, use API paths the runtime does not serve, so a request from them returns `404`. Pointed at the provider directly, they bypass Xenovia entirely, so those calls are neither traced nor policy-checked.
>
> ### Chains
>
> Every LLM call in a chain routes through Xenovia individually, and each call gets its own trace.
>
> ```python theme={null}
> from langchain_core.prompts import ChatPromptTemplate
>
> prompt = ChatPromptTemplate.from_messages([
>     ("system", "You are a helpful assistant."),
>     ("user", "{input}")
> ])
>
> chain = prompt | llm
> response = chain.invoke({"input": "What is LangChain?"})
> print(response.content)
> ```
>
> ### Agents with tools
>
> The example uses LangChain 1.x `create_agent`. Older examples using `create_tool_calling_agent` and `AgentExecutor` from `langchain.agents` do not work on 1.x. The request-stage policy evaluates `input.tool_names` before the call reaches the model. This checks the tools offered to the model, separately from authorizing a local action using model-generated arguments.
>
> ```python theme={null}
> from langchain.agents import create_agent
> from langchain_core.tools import tool
>
> @tool
> def search(query: str) -> str:
>     """Search the web for information."""
>     return f"Results for: {query}"
>
> agent = create_agent(
>     model=llm,
>     tools=[search],
>     system_prompt="Use search to find information when asked."
> )
> result = agent.invoke({
>     "messages": [{"role": "user", "content": "Search for recent AI news"}]
> })
> print(result["messages"][-1].content)
> ```
>
> ### RAG pipeline
>
> The generation step routes through Xenovia. Point the embeddings client directly at your provider: an embeddings call sent to the agent endpoint returns `404`, and embedding calls are not governed by Xenovia today.
>
> ```python theme={null}
> from langchain_openai import OpenAIEmbeddings
> from langchain_core.vectorstores import InMemoryVectorStore
>
> embeddings = OpenAIEmbeddings(
>     api_key=os.environ["OPENAI_API_KEY"]  # embeddings go straight to the provider
> )
>
> vectorstore = InMemoryVectorStore.from_texts(
>     ["Xenovia provides runtime governance for AI agents"],
>     embedding=embeddings
> )
> retriever = vectorstore.as_retriever()
>
> # Combine retriever with LLM
> from langchain_core.runnables import RunnablePassthrough
> from langchain_core.output_parsers import StrOutputParser
> from langchain_core.prompts import ChatPromptTemplate
>
> rag_prompt = ChatPromptTemplate.from_messages([
>     ("system", "Answer using this context:\n{context}"),
>     ("user", "{question}")
> ])
>
> rag_chain = (
>     {"context": retriever, "question": RunnablePassthrough()}
>     | rag_prompt
>     | llm
>     | StrOutputParser()
> )
> answer = rag_chain.invoke("What does Xenovia provide?")
> ```
>
> ### Session tracking
>
> The setup sets `X-Xenovia-Session-Id` on the client before constructing chains or agents, so all their LLM calls stay grouped in **Sessions**. Reuse it for the conversation, and create a new client and session ID for a separate conversation. Reassigning `llm` after creating a chain or agent does not update the client it already holds.
>
> ### Handling policy blocks
>
> The agent run ends normally with the refusal as its reply, `finish_reason: "content_filter"`. Because the setup sets `include_response_headers=True`, each reply's `response_metadata["headers"]` holds the response headers, with lowercase names:
>
> ```python theme={null}
> result = agent.invoke({
>     "messages": [{"role": "user", "content": "Delete all records"}]
> })
> reply = result["messages"][-1]
> headers = reply.response_metadata.get("headers", {})
>
> if headers.get("x-xenovia-decision") == "blocked":
>     print(f"Blocked by policy; trace: {headers.get('x-xenovia-trace-id')}")
> else:
>     print(reply.content)
> ```
>
> With `with_structured_output`, LangChain raises `OpenAIRefusalError` (from `langchain_openai.chat_models.base`) for a refusal.

> [tab] LlamaIndex
>
> Use `llama_index.llms.openai.OpenAI` for every provider the agent can route to, including Anthropic, Groq, Bedrock and Gemini. Provider-native LlamaIndex classes for Groq, Bedrock or Gemini use API paths the runtime does not serve. The `model` argument is a placeholder that the runtime replaces with the agent's configured model.
>
> ### Setup
>
> The agent example uses the workflow API available in LlamaIndex 0.13 and later, and needs an agent configured with a model that supports native tool calling. It is checked with Python 3.12, `llama-index-core` 0.13.0 / `llama-index-llms-openai` 0.5.0 and core 0.14.24 / OpenAI integration 0.8.1 using simulated HTTP responses. Validate your agent's policies, guardrails, and provider configuration separately.
>
> ```bash theme={null}
> pip install "llama-index-core>=0.13" llama-index-llms-openai llama-index-embeddings-openai llama-index-readers-file
> export XENOVIA_API_KEY=xe_...
> export XENOVIA_AGENT_ID=your-agent-id
> ```
>
> ```python theme={null}
> import os
> import uuid
> import openai
> from llama_index.llms.openai import OpenAI
> from llama_index.core import Settings
>
> session_id = str(uuid.uuid4())
> blocked_traces = []  # trace IDs of calls Xenovia blocked
>
>
> def note_block(response):
>     if response.headers.get("X-Xenovia-Decision") == "blocked":
>         blocked_traces.append(response.headers.get("X-Xenovia-Trace-Id"))
>
>
> async def anote_block(response):
>     note_block(response)
>
>
> llm = OpenAI(
>     model="gpt-4o-mini",  # placeholder: the agent's configured model is used
>     api_key=os.environ["XENOVIA_API_KEY"],
>     api_base=f"https://runtime.xenovia.io/{os.environ['XENOVIA_AGENT_ID']}/v1",
>     default_headers={"X-Xenovia-Session-Id": session_id},
>     http_client=openai.DefaultHttpxClient(event_hooks={"response": [note_block]}),
>     async_http_client=openai.DefaultAsyncHttpxClient(event_hooks={"response": [anote_block]}),
> )
>
> Settings.llm = llm
> ```
>
> Setting `Settings.llm` applies to all LlamaIndex components that use an LLM: query engines, chat engines and agents.
>
> LlamaIndex does not expose response headers, so the two HTTP clients record the trace ID of every call Xenovia blocks. `blocked_traces` is shared by every call through this client; in a server that handles requests concurrently, keep it per request, for example in a `contextvars.ContextVar`.
>
> ### Embeddings and RAG
>
> Keep the embedding model pointed directly at your provider. An embeddings call sent to the agent endpoint returns `404`. Only the LLM calls (query synthesis, chat, agent steps) are governed and traced by Xenovia today.
>
> ```python theme={null}
> from llama_index.embeddings.openai import OpenAIEmbedding
> from llama_index.core import VectorStoreIndex, SimpleDirectoryReader
>
> Settings.embed_model = OpenAIEmbedding(
>     api_key=os.environ["OPENAI_API_KEY"]  # embeddings go straight to the provider
> )
>
> documents = SimpleDirectoryReader("./docs").load_data()
> index = VectorStoreIndex.from_documents(documents)
>
> query_engine = index.as_query_engine()
> response = query_engine.query("What are the main topics covered?")
> print(response)
> ```
>
> ### Agentic query engine
>
> Use `FunctionAgent` so tool definitions are sent as native `tools` metadata. The `QueryEngineTool` below reuses the query engine above.
>
> ```python theme={null}
> import asyncio
> from llama_index.core.agent.workflow import FunctionAgent
> from llama_index.core.tools import QueryEngineTool
>
> tool = QueryEngineTool.from_defaults(
>     query_engine=query_engine,
>     name="docs_search",
>     description="Search internal documentation"
> )
>
> agent = FunctionAgent(
>     tools=[tool],
>     llm=llm,
>     system_prompt="Use docs_search to answer questions about internal documentation."
> )
>
> async def main():
>     response = await agent.run(user_msg="Find information about governance policies")
>     print(response)
>
> if __name__ == "__main__":
>     asyncio.run(main())
> ```
>
> In a notebook, use `await main()` instead of `asyncio.run(main())`. The older `ReActAgent.from_tools(...)` and synchronous `.chat()` examples do not apply to workflow agents. Each LLM call, including query synthesis inside `docs_search`, routes through Xenovia, and the session header set during setup groups them in **Sessions**. Replacing `llm` after creating an agent does not update the client already held by that agent.
>
> ### Handling policy blocks
>
> LlamaIndex returns the refusal like any other answer, and the setup's HTTP clients record its trace ID. For a direct query-engine call, then for the agent above:
>
> ```python theme={null}
> blocked_traces.clear()
> response = query_engine.query("Drop the database")
>
> if blocked_traces:
>     print(f"Blocked by policy; trace: {blocked_traces[-1]}")
> else:
>     print(response)
> ```
>
> ```python theme={null}
> async def run_with_policy_handling(message: str):
>     blocked_traces.clear()
>     response = await agent.run(user_msg=message)
>     if blocked_traces:
>         print(f"Blocked by policy; trace: {blocked_traces[-1]}")
>         return None
>     return response
> ```
>
> Call `await run_with_policy_handling(...)` from your async entry point. Unrelated failures still raise as usual. FunctionAgent streams by default; the decision headers arrive before the first chunk, so the hook sees them on streamed calls too.

> [tab] OpenAI Agents SDK
>
> Pair the Agents SDK with Xenovia through the **Responses API** (`POST /v1/responses`). The examples are written against `openai-agents` 0.24.
>
> ```bash theme={null}
> pip install "openai-agents>=0.24"
> ```
>
> ```python theme={null}
> import os
> from openai import AsyncOpenAI, DefaultAsyncHttpxClient
> from agents import Agent, Runner, OpenAIResponsesModel
>
> blocked_traces = []  # trace IDs of calls Xenovia blocked
>
>
> async def note_block(response):
>     if response.headers.get("X-Xenovia-Decision") == "blocked":
>         blocked_traces.append(response.headers.get("X-Xenovia-Trace-Id"))
>
>
> client = AsyncOpenAI(
>     api_key=os.environ["XENOVIA_API_KEY"],
>     base_url=f"https://runtime.xenovia.io/{os.environ['XENOVIA_AGENT_ID']}/v1",
>     http_client=DefaultAsyncHttpxClient(event_hooks={"response": [note_block]}),
> )
>
> model = OpenAIResponsesModel(
>     model="gpt-4o-mini",  # placeholder: the agent's configured model is used
>     openai_client=client
> )
>
> agent = Agent(name="Assistant", instructions="You are a helpful assistant.", model=model)
> result = await Runner.run(agent, "What is the capital of France?")
> print(result.final_output)
> ```
>
> The `http_client` hook records the trace ID of every call Xenovia blocks, because the Agents SDK does not expose response headers. Keep `blocked_traces` per run in a server that handles runs concurrently.
>
> > [!TIP]
> >
> > The Agents SDK exports its own traces to OpenAI using `OPENAI_API_KEY`, and logs a warning when that key is not set. Call `agents.set_tracing_disabled(True)` if you don't use OpenAI's trace viewer. Xenovia traces every call either way.
>
> ### Runs, sessions and handoffs
>
> Each `Runner.run` call may produce several Responses API turns, each traced on its own. A request that carries `previous_response_id` joins the session of the response it names. To group separate runs, add `default_headers={"X-Xenovia-Session-Id": session_id}` to the client; an explicit session ID takes priority over the `previous_response_id` chain.
>
> In a handoff, each agent calls the Responses API independently, and the session shows the whole conversation in order. Every agent here uses the same Xenovia agent and key, so the same policies and guardrails apply to all of them. To add checks for one step, give that step's client a key scoped to a [sub-agent](https://docs.xenovia.io/agents/sub-agents.md).
>
> Tool names defined on an agent are included in `input.tool_names`. A block rule matching a tool name stops the call before the model is called.
>
> ### Handling policy blocks
>
> On the Responses API the runtime answers `200` with `status: "incomplete"`, `incomplete_details.reason: "content_filter"`, and a refusal content part. `openai-agents` 0.24 treats an incomplete response as a failed turn and raises `ModelBehaviorError`. Catch it, and use the recorded header to tell a Xenovia block from any other failure:
>
> ```python theme={null}
> from agents import ModelBehaviorError
>
> blocked_traces.clear()
> try:
>     result = await Runner.run(agent, "Delete all user records")
>     print(result.final_output)
> except ModelBehaviorError:
>     if not blocked_traces:
>         raise  # not a Xenovia block
>     print(f"Blocked by policy; trace: {blocked_traces[-1]}")
> ```

> [tab] Vercel AI SDK
>
> The examples target AI SDK 7: `ai` 7.x with `@ai-sdk/openai` 4.x. Earlier major versions name some of these APIs differently.
>
> ```bash theme={null}
> npm install ai@7 @ai-sdk/openai@4 zod
> ```
>
> ```typescript theme={null}
> import { createOpenAI } from "@ai-sdk/openai"
>
> const xenovia = createOpenAI({
>   apiKey: process.env.XENOVIA_API_KEY,
>   baseURL: `https://runtime.xenovia.io/${process.env.XENOVIA_AGENT_ID}/v1`
> })
>
> // Chat Completions. The model ID is a placeholder: the agent's configured model is used.
> const model = xenovia.chat("gpt-4o-mini")
> ```
>
> `xenovia.chat(...)` calls `/v1/chat/completions`. Calling the provider directly, as `xenovia("gpt-4o-mini")`, uses the Responses API instead. Both work, but the runtime always buffers Responses API streams, while Chat Completions streams can go live.
>
> ### Next.js route handler
>
> The AI SDK does not add session IDs. Provide a stable UUID per conversation from your application:
>
> ```typescript theme={null}
> // app/api/chat/route.ts
> import { convertToModelMessages, streamText, type UIMessage } from "ai"
> import { createOpenAI } from "@ai-sdk/openai"
> import { randomUUID } from "crypto"
>
> export async function POST(req: Request) {
>   const { messages, sessionId }: { messages: UIMessage[]; sessionId?: string } = await req.json()
>
>   const xenovia = createOpenAI({
>     apiKey: process.env.XENOVIA_API_KEY,
>     baseURL: `https://runtime.xenovia.io/${process.env.XENOVIA_AGENT_ID}/v1`,
>     headers: {
>       // A stable session UUID from the client groups conversation turns
>       "X-Xenovia-Session-Id": sessionId ?? randomUUID(),
>       // Tag traces with application context
>       "X-Xenovia-Property-route": "chat",
>     }
>   })
>
>   const result = streamText({
>     model: xenovia.chat("gpt-4o-mini"),
>     messages: await convertToModelMessages(messages)
>   })
>
>   return result.toUIMessageStreamResponse()
> }
> ```
>
> ### Tool calling
>
> Tool schemas are forwarded to the model, and the request-stage policy evaluates `input.tool_names` first. Each step is its own call through Xenovia, with its own trace.
>
> ```typescript theme={null}
> import { stepCountIs, streamText, tool } from "ai"
> import { z } from "zod"
>
> const result = streamText({
>   model,
>   messages: [{ role: "user", content: "What is the weather in London?" }],
>   tools: {
>     getWeather: tool({
>       description: "Get the weather for a location",
>       inputSchema: z.object({ location: z.string() }),
>       execute: async ({ location }) => ({ temperature: "15°C", location })
>     })
>   },
>   stopWhen: stepCountIs(5) // let the model answer after the tool runs
> })
> ```
>
> ### Handling policy blocks
>
> Nothing throws. The AI SDK reports a refusal with `finishReason: "content-filter"`. Each step's `response.headers` holds the response headers, with lowercase names:
>
> ```typescript theme={null}
> const result = streamText({
>   model,
>   messages,
>   onStepEnd: (step) => {
>     const headers = step.response.headers ?? {}
>     if (headers["x-xenovia-decision"] === "blocked") {
>       console.warn("Blocked by policy. Trace:", headers["x-xenovia-trace-id"])
>     }
>   }
> })
>
> return result.toUIMessageStreamResponse()
> ```
>
> The refusal reaches your user like any other reply.

> [tab] AutoGen and CrewAI
>
> Both frameworks can target OpenAI-compatible endpoints. Point them at your agent endpoint and keep a stable session header for the whole run.
>
> ### AutoGen
>
> The example uses the current `autogen-agentchat` and `autogen-ext[openai]` packages rather than the older `pyautogen` setup.
>
> ```bash theme={null}
> pip install -U "autogen-agentchat" "autogen-ext[openai]"
> ```
>
> ```python theme={null}
> import asyncio
> import os
> import uuid
> from autogen_agentchat.agents import AssistantAgent
> from autogen_ext.models.openai import OpenAIChatCompletionClient
> from openai import DefaultAsyncHttpxClient
>
> session_id = str(uuid.uuid4())
> blocked_traces = []  # trace IDs of calls Xenovia blocked
>
>
> async def note_block(response):
>     if response.headers.get("X-Xenovia-Decision") == "blocked":
>         blocked_traces.append(response.headers.get("X-Xenovia-Trace-Id"))
>
>
> model_client = OpenAIChatCompletionClient(
>     model="gpt-4o-mini",  # placeholder: the agent's configured model is used
>     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": session_id},
>     http_client=DefaultAsyncHttpxClient(event_hooks={"response": [note_block]}),
> )
>
> assistant = AssistantAgent(
>     "assistant",
>     model_client=model_client,
>     system_message="You are a helpful assistant."
> )
>
> async def main() -> None:
>     blocked_traces.clear()
>     result = await assistant.run(task="Summarise the key principles of AI governance.")
>     if blocked_traces:
>         print(f"Blocked by policy; trace: {blocked_traces[-1]}")
>     else:
>         print(result.messages[-1].content)
>
> asyncio.run(main())
> ```
>
> `OpenAIChatCompletionClient` passes `http_client` to the OpenAI client, and the hook records the trace ID of each call Xenovia blocks. AutoGen may warn that the resolved model does not match `model`: the reply names the model configured on the agent.
>
> ### CrewAI
>
> ```bash theme={null}
> pip install crewai
> ```
>
> ```python theme={null}
> import os, uuid
> from crewai import Agent, Task, Crew, LLM
>
> session_id = str(uuid.uuid4())
>
> llm = LLM(
>     model="openai/gpt-4o-mini",
>     api_key=os.environ["XENOVIA_API_KEY"],
>     base_url=f"https://runtime.xenovia.io/{os.environ['XENOVIA_AGENT_ID']}/v1",
>     extra_headers={"X-Xenovia-Session-Id": session_id}
> )
>
> researcher = Agent(
>     role="Researcher",
>     goal="Find accurate information on the given topic",
>     backstory="You are an expert researcher with strong analytical skills.",
>     llm=llm
> )
>
> research_task = Task(
>     description="Research AI governance frameworks",
>     expected_output="A summary of key AI governance principles",
>     agent=researcher
> )
>
> crew = Crew(agents=[researcher], tasks=[research_task])
> print(crew.kickoff())
> ```
>
> With CrewAI, a refusal becomes that step's answer and the crew goes on with it. Open the session in **Sessions** to see which turn was blocked and why.
>
> ### How multi-agent traces work
>
> Each framework agent's turn is a separate call through the agent endpoint. Each call gets its own `X-Xenovia-Trace-Id`, is evaluated independently by the agent's policies and guardrails, and is grouped under the shared `X-Xenovia-Session-Id`.

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](https://docs.xenovia.io/observability/sessions.md#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](https://docs.xenovia.io/reference/runtime.md#2-session)).

### 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](https://docs.xenovia.io/observability/sessions.md#enriching-a-turn) for the rules.

### Response headers

| Header | Value |
| - | - |
| `X-Xenovia-Trace-Id` | The trace for this call |
| `X-Xenovia-Session-Id` | The session the call joined |
| `X-Xenovia-Decision` | `allowed`, `blocked`, or `unchecked` |
| `X-Xenovia-Reason` | Why a call was blocked or unchecked, such as `policy:<rule>` |
| `X-Xenovia-Decision-Id` | The Neon decision, when Neon decided |
| `X-Xenovia-Retried` | `true` when the answer is the second attempt |
| `X-Xenovia-Stream-Mode` | `live` or `buffered`, on streamed responses |

## Paths the runtime serves

| Endpoint | Use case |
| - | - |
| `POST /{agent_id}/v1/chat/completions` | Chat, agents, tool calling |
| `POST /{agent_id}/v1/responses` | OpenAI Agents SDK and multi-step runs |
| `POST /{agent_id}/v1/messages` | Anthropic SDKs, Claude Agent SDK, Claude Code |
| `POST /{agent_id}/v1/messages/count_tokens` | Token count estimates for Anthropic clients |
| `POST /v1/execute` | [Xenovia SDK](https://docs.xenovia.io/sdk/quickstart.md) checks. The key names the agent |

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](https://docs.xenovia.io/sdk/quickstart.md).

## What next?

> [card] [Add a policy](https://docs.xenovia.io/control/policies.md)
>
> Block one thing your agent should never do.

> [card] [Read a session](https://docs.xenovia.io/observability/sessions.md)
>
> See each call, check and decision.

> [card] [Split an agent into steps](https://docs.xenovia.io/agents/sub-agents.md)
>
> Give one step its own key and checks.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.