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

# Neon

> Xenovia's decision model checks every stage of a call for risks, your guardrails and the agent's purpose.

Catch what no rule named. Neon checks every stage of a call for prompt injection, data leaks, tool calls that go further than asked and requests outside the agent's purpose, together with the guardrails you write in plain language.

For example, a tool result carries a hidden instruction to email the customer list elsewhere. No policy names it, but Neon's **Input** risks fire at the tool result stage. In Monitor it is recorded; in Enforce the call is refused.

Neon is the model that decides whether a call to your agent goes ahead. It governs every agent, so there is nothing to switch on. At each stage of a call, the runtime sends Neon what that stage carries, in one request, together with:

* the agent's **protections**: what each of Neon's trained risks does when it fires,
* the agent's **guardrails**: rules you write for this agent,
* at the model request, the agent's **purpose** and **capabilities**.

Neon scores all of them in one pass and returns one verdict for the stage. [Policies](https://docs.xenovia.io/control/policies.md) run first at the same stage. A policy block stops the call before Neon sees it, and a policy redaction is applied before Neon judges the material.

You set all of this on the agent's **Neon** tab. Its header, **Neon is governing this agent**, says how many risks it enforces. While it enforces none, the tab notes that Neon records what it finds and blocks nothing.

## Stages

| Stage | What Neon judges | Sent from |
| - | - | - |
| Model request | The messages, system prompt and tool definitions, before the provider is called. The purpose and capabilities are checked here | The agent endpoint and the Python SDK |
| Tool result | Each tool result your app sends back in a request, and what a provider-hosted tool returned in a reply | The agent endpoint and the Python SDK |
| Model response | The model's reply. Its reasoning is checked for data leaks only | The agent endpoint and the Python SDK |
| Tool call | Each tool call the model proposes | The agent endpoint and the Python SDK |
| Memory write | What your code is about to store in memory | The [Python SDK](https://docs.xenovia.io/sdk/quickstart.md) only |
| Context summary | A summary your code writes to replace earlier context | The [Python SDK](https://docs.xenovia.io/sdk/quickstart.md) only |

## What Neon decides

| Verdict | Effect |
| - | - |
| Allow | The call goes on |
| Block | The call is refused with a `200` refusal in the format of the API you called (see [Blocks and refusals](https://docs.xenovia.io/observability/sessions.md#what-a-block-looks-like-to-your-app)). A blocked reply or tool call is first retried once |
| Redact | Neon names the text to mask. The runtime checks that each piece is really in the content before masking it. If it can't, it blocks instead |
| Escalate | The call goes on and an [escalation](https://docs.xenovia.io/control/policies.md#escalations) is recorded for review |

When the agent enforces anything on the reply, a streamed reply is buffered and checked before any of it is sent. When nothing is enforced on the reply, the stream goes to your app as the model produces it. Neon still judges the reply afterwards and records what it would have done.

## Protections

Neon checks 35 trained risks, grouped into nine families, at every stage they apply to. Under **Risks** on the **Neon** tab, choose what each family does **When one fires**:

| Setting | Effect |
| - | - |
| **Enforce** | Neon acts on it: the call can be blocked or redacted |
| **Monitor** | Neon records what it found and changes nothing |
| **Off** | Neon still checks it and only records it. The console hides it |

**Default for all risks** sets every family you haven't set yourself. Until you change it, everything is in **Monitor**: Neon records what it finds and blocks nothing. The most specific setting wins: a single risk over its family, and a family over the default.

| Family | What it covers | Risks |
| - | - | - |
| Input | Prompt injection and attempts to override the operator | 4 |
| Memory | Poisoned memories and summaries that drop rules | 2 |
| Tools | Tool calls that go further than the user asked | 6 |
| Data | Leaks of personal data, secrets and records | 4 |
| Output | Replies that mislead, discriminate or give unsafe advice | 4 |
| Multi-agent | Abuse of delegation between agents | 2 |
| Supply chain | Untrusted components pulled into the run | 1 |
| Operations | Destructive, wasteful, off-purpose or unverified actions | 4 |
| Vulnerabilities | Vulnerable code, dependencies and exploit attempts | 8 |

Hover the icon beside a family to see the risks it covers.

### Set protections with the API

`GET /api/v1/agents/{agent_id}/neon` returns the agent's `protections`. `PUT` to the same path replaces them:

```json theme={null}
{
  "protections": [
    { "target": "*", "action": "monitor" },
    { "target": "risk.data.", "action": "enforce" },
    { "target": "risk.ops.off_purpose", "action": "enforce" }
  ]
}
```

A `target` is `*` (the default), a family as `risk.<family>.`, or one risk as `risk.<family>.<risk>`. The family keys are `input`, `memory`, `tools`, `data`, `output`, `multiagent`, `supply`, `ops` and `vuln`. `action` is `enforce`, `monitor` or `off`. A list holds up to 200 entries, and a target that appears twice is refused with `422`. A change reaches the runtime within about five minutes and is recorded in the audit log as `neon.settings.update`.

## Purpose and capabilities

The agent's **Purpose**, on its **Overview**, says in plain language what the agent is for (up to 4,000 characters). Its **Capabilities** tab names the things it does, such as "Track orders", each with an optional description and up to 10 example requests. An agent can have up to 50 capabilities.

Neon checks every model request against the purpose and, when the agent has enabled capabilities, requires it to match one of them too. The purpose has its own **Mode**:

* **Monitor** (the default) records requests outside the purpose without blocking them.
* **Enforce** blocks requests outside the purpose or its capabilities. When the check can't run, the call fails closed (see [When Neon can't be reached](#when-neon-cant-be-reached)).

In **Sessions**, a request that failed the check shows **Outside this agent's purpose** or **Matches none of this agent's capabilities**. A capability that an [inline sub-agent](https://docs.xenovia.io/agents/sub-agents.md) adds counts only for that sub-agent's calls.

Through the API, set `purpose` and `purpose_mode` (`monitor` or `enforce`) with `PATCH /api/v1/agents/{agent_id}`, and manage capabilities under `/api/v1/agents/{agent_id}/capabilities`.

## Guardrails

A guardrail is a rule you write for one agent. Neon checks it alongside the risks, in the same pass. Add one under **Your rules** on the **Neon** tab with **Add guardrail**:

| Field | What it sets |
| - | - |
| **Name** | How the guardrail appears in the console and in Sessions |
| **Kind** | What it watches for (see below) |
| **Instructions** | Required for **Custom** and **Scope**. Optional extra guidance for the other kinds |
| **Where to run** | One or more stages: Model request, Model response, Tool call, Tool result, Memory write, Context summary |
| **Action** | **Allow**, **Block**, **Redact**, or **Allow and flag for review**, which records an escalation and lets the call go on |
| **Mode** | **Monitor** records findings without blocking or changing content. **Enforce** applies the action |
| **Enabled** | Turns the guardrail on or off |

| Kind | What it does |
| - | - |
| **Scope** | Limits what requests may ask the agent, or one of its sub-agents, to do |
| **Custom** | Your own guardrail, written in plain language |
| **Memory write** | Reviews what the agent tries to remember |
| **Context summary** | Reviews summaries the agent writes of earlier context |
| **Doing more than asked** | Flags actions beyond what the user requested |
| **Off purpose** | Flags work outside the agent's stated purpose |
| **Customer reply** | Reviews replies for tone, accuracy and commitments |
| **Wrong instruction** | Flags instructions that contradict the system prompt |
| **Unfair decision** | Flags decisions that treat people inconsistently |
| **Deception** | Flags misleading or dishonest statements |

A **Memory write** or **Context summary** guardrail runs only at its own stage, and those two stages accept only their own kind or a **Custom** guardrail. Both stages come only from the [Python SDK](https://docs.xenovia.io/sdk/quickstart.md). A guardrail can be added to one [inline sub-agent](https://docs.xenovia.io/agents/sub-agents.md), where it runs on that sub-agent's calls after the agent-wide guardrails.

Through the API, guardrails are under `/api/v1/agents/{agent_id}/slm-checks` (`GET` and `POST`, then `PATCH` and `DELETE` on `/{check_id}`). The body takes `name`, `kind`, `prompt`, `stages`, `action`, `enforcement_mode`, `enabled` and `sub_agent_id`. `action` defaults to `block` and `enforcement_mode` to `monitor`.

## How decisions show up

Every response carries `X-Xenovia-Decision`. When Neon decided the stage, `X-Xenovia-Decision-Id` names its decision. On a block, `X-Xenovia-Reason` says what decided it: a risk ID such as `risk.data.secret_exposure`, `purpose` for the purpose check, or the ID of the guardrail that blocked. See [Blocks and refusals](https://docs.xenovia.io/observability/sessions.md#what-a-block-looks-like-to-your-app) for all the headers.

In **Sessions**, each stage Neon judged has a **Neon** step. **What Neon found** lists each risk or guardrail that fired, with its probability and whether it **Blocked**, **Redacted** or was only **Recorded**. Choose **Explain this decision** to have Neon say **Why it fired**, or **Why it stayed below the line** for one that didn't.

To get the same explanation through the API, call `POST /api/v1/agents/{agent_id}/neon/decisions/{decision_id}/explain` with the decision ID from the header or the session. You can pass `{"question": "<risk id>"}` to ask about one risk. By default Neon explains its most probable finding. An unknown decision returns `404`.

## When Neon can't be reached

What happens depends on whether the stage enforces anything: an enforced guardrail, a protection in **Enforce**, or, at the model request, a purpose in **Enforce**.

* **Something is enforced.** The runtime fails closed: it answers `503` with `Retry-After: 5`. At the model request, nothing is sent to the provider.
* **Nothing is enforced.** The call goes on without a verdict, and `X-Xenovia-Decision` says `unchecked`.

In a [simulation](https://docs.xenovia.io/simulation.md) run with **Policies** set to **Shadow**, Neon judges every stage and records what it would have done, but nothing is blocked.

## What next?

> [card] [Policies](https://docs.xenovia.io/control/policies.md)
>
> Hard rules that run before Neon.

> [card] [Sessions](https://docs.xenovia.io/observability/sessions.md)
>
> Read what Neon found and why.

> [card] [Simulation](https://docs.xenovia.io/simulation.md)
>
> Attack your agent to test Neon.


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