> For clean Markdown of any page, append .md to the page URL.
> For a complete documentation index, see https://developers.alephant.io/llms.txt.
> For AI client integration (Claude Code, Cursor, etc.), connect to the MCP server at https://developers.alephant.io/_mcp/server.

# Guardrails

> Govern model access, agent behavior, session cost, security, and routing

Guardrails are the policy and enforcement framework around traffic that passes through Alephant. They are not one filter or one rule. They connect model-access policy, Agent-specific policy, Session cost controls, security controls, and the logs that explain each decision.

Use Guardrails to define what a workspace, department, member, Virtual Key, Agent, or Session is allowed to access and spend. Configuration lives in the Alephant control plane; the relevant Gateway and backend runtime apply the effective policy.

## How Guardrails fit together

| Policy surface        | Primary scope                                       | What it controls                                                                                       |
| --------------------- | --------------------------------------------------- | ------------------------------------------------------------------------------------------------------ |
| LLM Policy            | Workspace, department, member, and Virtual Key      | Model access, budgets, request and token limits, security controls, and routing behavior               |
| Agent Policy          | Workspace, department, or individual Agent bindings | Allowed models, Agent budgets, run limits, retry behavior, tracking requirements, and tool permissions |
| Session Cost Controls | Requests sharing one `session_id`                   | Per-Session budget, cumulative cost, burst protection, model downgrade, and Agent-specific overrides   |

Guardrails complement Endpoint Policy and Spend Policy, but those products govern different runtime boundaries. Endpoint Policy controls published endpoints, while Spend Policy controls outbound Agent payments.

## LLM Policy

LLM Policy governs calls made through Alephant Virtual Keys. Open **Control → LLM Policy** in the Dashboard to view the controls available for the current workspace, plan, and deployment.

### Access control

Access controls determine which callers and resources can use the Gateway:

* **Model Allowlist** restricts requests to approved models.
* **IP/CIDR Allowlist** restricts Gateway access to approved network ranges.
* **Department Key Access** controls which departments can use specific Master Keys.

Keep model and key access narrow enough to match the workload. A fallback or optimization rule must not route around an access restriction.

### Usage limits

Usage limits protect budgets and upstream capacity:

* Workspace budget with monthly or quarterly periods, warning thresholds, and an exceeded action
* Daily hard stops and monthly spend alerts
* Custom request limits such as RPM, RPH, and burst allowance
* Concurrent request and token limits
* Member budget caps for Virtual Keys
* Department-level budget and rate overrides

Some controls are always on, some can be enabled or disabled, and others require a specific plan. The Dashboard shows the current status and availability instead of treating every listed control as active.

### Security and compliance

Enterprise workspaces can expose additional controls:

* Time-based access windows
* PII detection with block, redact, or alert behavior
* Audit logging for API requests and policy actions

Availability depends on the workspace plan and deployment. Review the displayed policy status before relying on a control in production.

### Smart routing and optimization

Routing-related Guardrails can include model fallback, semantic caching, provider-key load balancing, and cost-aware routing. These controls also depend on the configured routing mode, managed credits, provider access, and whether the workspace uses managed routing or only BYO keys.

Do not assume that a visible routing option is active. Check its status in the Dashboard and review [Routing Optimization](/ai-gateway/routing-optimization) for routing-specific behavior.

## Agent Policy

Agent Policy defines reusable policy profiles and binds them to a workspace, department, or individual Agent. Open **Control → Agent Policy** to create, edit, enable, disable, and bind profiles.

| Policy area  | Configurable values                                                                  |
| ------------ | ------------------------------------------------------------------------------------ |
| Model access | All models, provider default, or selected models                                     |
| Budget       | Monthly budget, maximum cost per run, and alert or block action                      |
| Runtime      | Runtime mode, required run tracking, maximum requests, maximum duration, and retries |
| Tools        | All tools, selected tools, or not configured                                         |
| Bindings     | Workspace default, departments, individual Agents, or a mixed scope                  |

Agent Policy is more specific than a general catalog of workspace controls: it follows an Agent across its runs and provides the Agent context used for attribution and policy evaluation. A configured field represents desired policy state; the backend and Gateway runtime remain the authority for whether and how that field is enforced.

## Session Cost Controls

Session Cost Controls govern a group of related model calls that share the same `session_id`.

| Control                | Purpose                                                                                |
| ---------------------- | -------------------------------------------------------------------------------------- |
| C1 — Budget Cap        | Set the maximum cost allowed for one Session and choose the supported intercept action |
| C2 — Cost Accumulation | Track cumulative cost across calls and associate threshold actions with the Session    |
| C3 — Rate Limiting     | Protect a Session from runaway loops and request bursts                                |
| C4 — Model Downgrade   | Switch from one configured model to a cheaper configured model near a cost threshold   |
| Per-Agent Overrides    | Override supported workspace defaults for selected Agents                              |

The Dashboard describes a rejected budget-cap request as HTTP `402` and a rejected rate-limit request as HTTP `429`. Exact response bodies and supported intercept actions depend on the deployed Gateway version, so applications should handle the HTTP status and inspect the returned error rather than depending on an undocumented message string.

Attach Session and Agent context to each request:

```bash
curl "$ALEPHANT_GATEWAY_BASE_URL/chat/completions" \
  -H "Authorization: Bearer $ALEPHANT_VIRTUAL_KEY" \
  -H "Content-Type: application/json" \
  -H "alephant-session-id: sess_support_8421" \
  -H "Alephant-Agent-Id: agt_support_bot" \
  -H "Alephant-Run-Id: run_support_8421_001" \
  -d '{
    "model": "openai/gpt-4o-mini",
    "messages": [
      { "role": "user", "content": "Classify this support request." }
    ]
  }'
```

Set `ALEPHANT_GATEWAY_BASE_URL` to the Gateway Base URL shown in the Dashboard. Alephant Cloud defaults to `https://ai.alephant.io/v1`; private deployments can expose a different runtime URL.

## Configure and verify a policy

1. Add a provider key and create the Virtual Key that will send Gateway traffic.
2. Open **Control → LLM Policy** or **Control → Agent Policy**.
3. Configure the policy, scope, status, and supported overrides.
4. Send a request through the configured Gateway Base URL with Agent, Run, and Session identifiers where applicable.
5. Inspect Request Logs for the serving provider, model, status, token usage, cost, and policy metadata.
6. Inspect Sessions for cumulative cost, intercepts, model changes, and per-Agent behavior.
7. Inspect Audit Logs for configuration and enforcement events exposed by the workspace.

When multiple scopes apply, verify the effective result in the target deployment before production rollout. This page does not define a universal precedence order for every policy type; the backend and Gateway contract for that policy is authoritative.

## Availability and enforcement

The Dashboard uses several states:

| State                     | Meaning                                                               |
| ------------------------- | --------------------------------------------------------------------- |
| Always On                 | A baseline control that cannot be disabled from the current workspace |
| Active / Off              | A persisted control that is enabled or disabled                       |
| Plan-gated                | The control is visible but requires another plan                      |
| Coming Soon / unavailable | The control is not available for the current product or runtime mode  |

Treat the configuration state, Gateway enforcement result, and observability record as three separate checks. A saved form confirms control-plane configuration; a request result and its logs confirm runtime behavior.

## Related pages

* [Provider Routing](/ai-gateway/provider-routing)
* [Routing Optimization](/ai-gateway/routing-optimization)
* [Session](/ai-gateway/session)
* [Policies & Rules](/docs/overview/security-compliance/policies-rules)
* [Agent Run Tracing](/docs/overview/core-concepts/agent-run-tracing)