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

# Xenovia SDK

> Check what your code does, before it runs: tool calls, memory writes, summaries and model calls.

Check what your code does, before it runs. For example, check an email before your agent sends it:

```python theme={null}
check = xenovia.tool_pre("send_email", {"to": to, "body": body})
if not check.is_success():
    return "This action is not allowed."
```

The Xenovia Python SDK (`xenovia-sdk`) sends an agent's actions to Xenovia for a decision before they happen: tool calls and tool results, memory writes, context summaries, and — for agents that call their model directly — the model request and reply. Each check runs the guardrails configured on the agent for that stage; `model_request`, `model_response`, and `tool_call` checks also run the agent's policies.

Use it alongside the [agent endpoint](https://docs.xenovia.io/agents/connect-your-app.md): the endpoint governs model traffic, and the SDK governs the steps your code takes around it. Tool, memory, and summary guardrails only run when the SDK sends those stages.

**Install:**

```bash theme={null}
pip install "xenovia-sdk>=0.3.0"
```

**Requirements:** Python ≥ 3.9. The SDK installs `httpx`, which only the [model call helpers](https://docs.xenovia.io/sdk/reference.md#route-model-calls-through-xenovia) use. Decisions are sent with the standard library.

## How it works

Every SDK call is a `POST /v1/execute` to the Xenovia runtime, authenticated with the agent's `xe_` API key. The key identifies the agent, so the request body does not name it.

```
agent code
  → xenovia.tool_pre("send_email", {"to": ..., "body": ...})
    → POST /v1/execute  (stage=tool_call, operation=send_email)
      → the agent's policies (model and tool_call stages) and guardrails for that stage
    ← decision: allow | redact (masked payload) | deny
  → run the tool with the returned arguments, or stop
```

The decision is one of:

| Outcome | `status` | What your code should do |
| - | - | - |
| `allow` | `success` | Proceed with the original values |
| `redact` | `success` | Proceed with the masked values in `response.payload` |
| `deny` | `blocked` | Stop; do not run the action |
| `error` | `failed` | Treat as not allowed |

The runtime reports failures such as a bad request, a rate limit, or an unavailable dependency as HTTP errors, which the SDK raises as `XenoviaExecutionError` (see [Error handling](https://docs.xenovia.io/sdk/reference.md#error-handling)).

`decision["escalated"]` is `true` when a guardrail escalated the step. The step is still allowed, and an escalation is queued for review (see [Escalations](https://docs.xenovia.io/control/policies.md#escalations)). A policy escalation, by contrast, denies the step.

## Initialise the client

```python theme={null}
import os
from xenovia_sdk import Xenovia

xenovia = Xenovia(
    api_key=os.environ["XENOVIA_API_KEY"],   # the agent's xe_ key
    auto_session=True,                       # let the runtime issue a session and reuse it
)
```

## Your first check

```python theme={null}
check = xenovia.tool_pre("send_email", {"to": to, "body": body})

if not check.is_success():  # blocked, or failed
    return "This action is not allowed."

args = check.payload["arguments"] if check.is_redacted() else {"to": to, "body": body}
result = send_email(**args)

reviewed = xenovia.tool_post("send_email", str(result))
if not reviewed.is_success():
    return "The tool result was withheld."
```

The check runs the guardrails configured on the agent for its stage and, for a `tool_call`, the agent's policies. Look up `trace_id` in **Sessions** to see which policy or guardrail fired.

## What next?

> [card] [Hooks](https://docs.xenovia.io/sdk/hooks.md)
>
> Every hook, execute() and @guard().

> [card] [Reference](https://docs.xenovia.io/sdk/reference.md)
>
> Options, sessions, errors and the wire format.

> [card] [Neon](https://docs.xenovia.io/control/neon.md)
>
> Write the guardrails your checks run.


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