Guardrails | Alephant Documentation

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 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:

$ 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

Add a provider key and create the Virtual Key that will send Gateway traffic.
Open Control → LLM Policy or Control → Agent Policy.
Configure the policy, scope, status, and supported overrides.
Send a request through the configured Gateway Base URL with Agent, Run, and Session identifiers where applicable.
Inspect Request Logs for the serving provider, model, status, token usage, cost, and policy metadata.
Inspect Sessions for cumulative cost, intercepts, model changes, and per-Agent behavior.
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.