AI Guardrails

Technical reference. This page is for integrations, advanced configuration, or platform operations. For portal tasks, start with the user guide.

Guardrails are Orqestra’s content-safety layer. They are configured as guardrail_config assets and enforced by the runtime on bound llm_call and agent steps.

Current Product Model

The current implementation should be understood this way:

• guardrail_config is a governed asset kind
• the active release binds a guardrail_config version
• the runtime loads that binding and evaluates content before and after model or agent execution
• guardrail outcomes are recorded as evidence artifacts

The current flow schema does not define a standalone guardrail step type, and current flows should not use a top-level guardrails: block as if it were part of the public flow contract.

Runtime-Enforced Checks

The current runtime enforces these checks:

The schema also reserves additional fields such as content_filter, but the enforced runtime behavior today is the set above.

Custom rule pattern values must be valid regexes no longer than 512 characters. Asset authoring rejects nested unbounded quantifier shapes such as (a+)+ before the guardrail version can be saved. If a persisted custom rule is invalid, unsafe, or exceeds the runtime match/redaction deadline, runtime evaluation fails closed and blocks the content instead of skipping the rule.

Guardrail Configuration

This shape matches the current runtime behavior:

{
  "pii_detection": {
    "enabled": true,
    "actions": {
      "email": "redact",
      "phone": "mask",
      "credit_card": "block",
      "ssn": "redact"
    }
  },
  "prompt_injection": {
    "enabled": true
  },
  "topic_denial": {
    "enabled": true,
    "denied_topics": ["internal_financials", "customer_secrets"],
    "refusal_message": "This topic is not allowed for this workload."
  },
  "custom_rules": [
    {
      "name": "block-root-password",
      "pattern": "(?i)root password",
      "action": "block"
    }
  ]
}

How Guardrails Are Applied

Guardrails are applied through the active release, not by embedding extra flow syntax around each step.

Typical setup:

1. create a guardrail_config asset
2. create a version with the desired configuration
3. bind that version to the release with role guardrail_config
4. activate the release

At runtime:

• llm_call steps are checked before the model call and after the model reply
• agent steps are checked before the agent goal is processed and after the final answer is produced

Example Asset Workflow

curl -X POST http://localhost:8000/v1/assets/ \
  -H "Content-Type: application/json" \
  -d '{
    "slug": "support-safety",
    "asset_kind": "guardrail_config",
    "owner_ref": "team:security"
  }'

curl -X POST http://localhost:8000/v1/assets/{asset_id}/versions \
  -H "Content-Type: application/json" \
  -d '{
    "version_label": "v1",
    "content": {
      "pii_detection": {
        "enabled": true,
        "actions": {
          "email": "redact",
          "phone": "mask"
        }
      },
      "prompt_injection": {
        "enabled": true
      }
    }
  }'

Bind that version into the release:

orqestractl release bind $RELEASE_ID --asset-version $GUARDRAIL_V1 --role guardrail_config

Evidence And Failure Modes

Every evaluation records a guardrail_event evidence artifact. The runtime can produce outcomes such as:

• blocked input before model execution
• sanitized/redacted content before continuing
• blocked final output
• warnings/violations preserved in evidence

If guardrails block content, the step does not silently continue.

Guardrail Attribution

Post-hoc attribution aggregates the guardrail_event evidence already recorded for one execution into three buckets: materialized (blocked, or otherwise took effect), mitigated (redacted or sanitized rather than blocked), and attempted (evaluated, no action taken). It never re-derives or re-runs a check — each guardrail evaluation already classifies its own outcome synchronously at check time; this endpoint only aggregates those recorded decisions. An execution with no guardrail_event rows returns zero counts, not a 404.

Reliability Certification

Judge and guardrail detectors can be certified against a versioned, human-labeled reliability suite. Certifying computes accuracy, sensitivity, specificity, and a Wilson-score confidence interval, and stores the result with a pass/fail verdict and an expiry (ttl_days, default 90 days). Certification is advisory: no release gate or live judge/guardrail dispatch reads a stored certification today.

orqestractl certification recertify \
  --detector-kind guardrail \
  --detector-id guardrail_config:support-safety \
  --detector-version v1 \
  --suite-slug pii-redaction-suite \
  --suite-version 1 \
  --case '{"case_id":"p1","human_label":true,"detector_prediction":true}' \
  --case '{"case_id":"n1","human_label":false,"detector_prediction":false}'
 
orqestractl certification get --detector-kind guardrail --detector-id guardrail_config:support-safety

Best Practices

Treat guardrails as release-bound safety controls. Keep them versioned and promoted like any other governed asset.

Start with focused rules. A few well-understood checks are better than a large, noisy rule set that operators cannot reason about.

Use policies and guardrails together. Policies decide whether a request should run at all. Guardrails inspect the content that flows through model and agent steps.

Document what is enforced today. If you choose to use schema fields that are not yet enforced by the runtime, do not rely on them as production controls.