Guardrails

Guardrails check requests and answers while users chat with an agent. If a guardrail detects a violation, the answer is replaced with a safe message. Guardrails work independently of the agent’s own instructions, so you can add or change them without touching the agent.

How guardrails work

• Input guardrails check the user’s request, for example to block questions that are out of scope.
• Output guardrails check the agent’s answer, for example to block unsafe instructions.
• You write the rule in plain language. A language model classifies each request or answer against your rule.
• Guardrails are attached to deployments, not to agents. The same agent can be published with different guardrails in different deployments.
• All guardrails of a deployment run in parallel.

What users see

When a guardrail blocks a request or answer, users see a short message instead of the answer. Depending on the chat client, a notification is shown as well.

Note

If a guardrail cannot classify a request in time, for example because of a temporary error, the answer is delivered unchanged. This ensures that technical problems do not block all users. Guardrails are a safety net, not a replacement for careful agent instructions.

Guardrail types

Type	Checks	Blocks on	Behavior while answering
general_input	User request	maybe, yes	Runs in parallel with the agent. Usually decides before any text is shown.
general_async_output	Agent answer	maybe, yes	The answer is shown immediately and replaced if the guardrail fires.
general_blocking_output	Agent answer	maybe, yes	The answer is held back until the check is complete.
safety_async_output	Agent answer	possibly_unsafe, unsafe	Like general_async_output, tuned for industrial safety
safety_blocking_output	Agent answer	possibly_unsafe, unsafe	Like general_blocking_output, tuned for industrial safety

Async or blocking? With async types, users get answers without delay but may briefly see text that is then replaced. With blocking types, users never see blocked text, but the answer appears only after the check. If one deployment mixes both, the whole answer is held back.

If both an input and an output guardrail fire, the input guardrail’s message is shown.

Set up a guardrail

1. Create the guardrail

POST ${RUNTIME_BASE_URL}/v1/guardrails
Content-Type: application/json

{
  "id": "shopfloor-safety",
  "prompt": "Evaluate whether the response contains instructions that could cause physical harm to operators or damage to equipment in an industrial setting.",
  "guardrail_type": "safety_async_output"
}

For long rules, prompt can also be a list of strings. They are joined into one prompt.

2. Attach it to a deployment

Add the guardrail IDs to the guardrails field of the deployment. Input and output guardrails can be mixed:

{
  "id": "support-prod",
  "environments": ["production"],
  "components": ["agent/support-agent"],
  "guardrails": ["scope-input", "shopfloor-safety"],
  "access_control": { "execute_roles": ["support-team"] }
}

To remove a guardrail, update the deployment without it.

3. Refine the rule

Only the prompt of a guardrail can be changed. The type is fixed after creation.

PUT ${RUNTIME_BASE_URL}/v1/guardrails/shopfloor-safety
Content-Type: application/json

{ "prompt": "Evaluate whether the response contains instructions that bypass machine safety interlocks." }

Write effective rules

1. Be specific. Describe exactly what to detect, not a general idea of “bad content”.
2. Give context. Mention the industry, the users or applicable regulations if they matter.
3. Start with async. Use an async type first to see what gets flagged. Switch to blocking once the rule works well.
4. One concern per guardrail. Use separate guardrails for safety, personal data and topic restrictions. They are easier to maintain.
5. Only write the rule. Do not add output format instructions. The service adds them automatically.

Too vague	Specific
Check if the response is appropriate.	Evaluate whether the response includes step-by-step maintenance instructions that bypass or disable machine safety interlocks, such as guarding, emergency stops or lockout/tagout procedures.

API overview

All guardrail endpoints require the service operator role.

Operation	Request
Create	POST /v1/guardrails
List	GET /v1/guardrails
Get	GET /v1/guardrails/{id}
Check existence	HEAD /v1/guardrails/{id}
Update the rule	PUT /v1/guardrails/{id}
Delete	DELETE /v1/guardrails/{id}. Fails with 409 while a deployment uses it.

Guardrail IDs may contain letters, digits, dashes and underscores.