LangChain

Xenovia is an OpenAI-compatible endpoint, so ChatOpenAI is the client for every Xenovia agent, whichever provider the agent routes to. The provider and model are configured on the agent and resolved server-side; the model argument in your code is a placeholder that the runtime replaces with the agent’s configured model.

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.

Python
Node.js

pip install "langchain>=1,<2" "langchain-openai>=1,<2"
export XENOVIA_API_KEY=xe_...
export XENOVIA_AGENT_ID=your-agent-id

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

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

Use ChatOpenAI no matter which provider is attached to the agent:

Provider attached to the agent	LangChain class to use
OpenAI, Azure OpenAI, Groq, Amazon Bedrock, Google Gemini, Anthropic, vLLM	`ChatOpenAI` pointed at the agent endpoint

Provider-native classes such as ChatGroq, ChatAnthropic, ChatBedrock, or ChatGoogleGenerativeAI use their own API paths and auth headers, so they cannot be pointed at the agent endpoint; a request from them returns 404. Pointed at the provider directly, they bypass Xenovia entirely, so those calls are neither traced nor policy-checked. The model argument is a placeholder. The runtime replaces it with the model configured on the agent, and the model field in the response reports the model that actually served the request. To change models, update the agent’s provider configuration rather than your code.

Chains

Use the configured llm in any LangChain chain. Every LLM call in the chain routes through Xenovia individually — each call gets its own trace.

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 Python 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. Tool definitions are passed to the upstream LLM through Xenovia. The request-stage Rego policy evaluates input.tool_names before the call reaches the model — a blocked tool returns 403 before the LLM is called. This checks the tools offered to the model, separately from authorizing a local action using model-generated arguments.

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. The runtime does not expose /v1/embeddings yet, so point the embeddings client directly at your provider — an embeddings call sent to the agent endpoint returns 404.

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 Python 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.

Forwarding the simulation session

Simulation sends your agent an X-Xenovia-Session-Id header with every turn. Pass it, unchanged, on each LLM call made for that turn:

session = request.headers.get("X-Xenovia-Session-Id")
reply = llm.invoke(messages, extra_headers={"X-Xenovia-Session-Id": session} if session else {})

Here llm is a ChatOpenAI built as in Setup but without default_headers. A session fixed on the client can’t follow Simulation, which runs several conversations at once, each with its own value. On the Xenovia cloud runtime the value is signed (xsim1.…) and a changed one is rejected with 400; on any runtime, a changed or dropped value means Simulation can’t grade a scenario’s tool and instruction-leak checks.

Handling policy blocks

LangChain propagates the upstream 403 as an openai.PermissionDeniedError. Catch it in your chain’s error handler.

from openai import PermissionDeniedError

try:
    result = agent.invoke({
        "messages": [{"role": "user", "content": "Delete all records"}]
    })
except PermissionDeniedError as e:
    trace_id = e.response.headers.get("X-Xenovia-Trace-Id")
    print(f"Blocked by policy: {e.message}; trace: {trace_id}")

Embedding calls are not governed by Xenovia today because the runtime does not expose /v1/embeddings. Keep OpenAIEmbeddings pointed at your provider and route only the chat model through the agent endpoint.

Start Here

Integrations

Platform

Setup

One client for every provider

Chains

Agents with tools

RAG pipeline

Session tracking

Forwarding the simulation session

Handling policy blocks

​Setup

​One client for every provider

​Chains

​Agents with tools

​RAG pipeline

​Session tracking

​Forwarding the simulation session

​Handling policy blocks

Setup

One client for every provider

Chains

Agents with tools

RAG pipeline

Session tracking

Forwarding the simulation session

Handling policy blocks