Guardrails

The Guardrail is an LLM classifier separate from the main model. It examines the text typed by the user before the agent responds and can stop the turn with a refusal. Use it as an additional layer against jailbreaks, prompt injection, role manipulation, instruction extraction, and violations of additional rules.

The feature reduces risk, but it is not a complete barrier: it operates in fail-open mode, analyzes only the current message text, and does not inspect content extracted from images, audio, or files. Keep explicit boundaries in the system prompt and validate the real flow as well.

Before you configure it

• You need permission to edit the agent.
• Save the main prompt first. Context generation uses the stored version, not an unsaved draft.
• Define allowed, blocked, and ambiguous examples. Legitimate sensitive questions should not be blocked merely because of their subject.
• Confirm that the selected model is allowed by the organization’s plan. This screen reads the global active-model catalog and may include an option outside the contracted catalog.

Configure it under Agents → Security

1. Open the agent and select Security in the sidebar.
2. Turn on Enable guardrail.
3. Under Model, select the classifier LLM. Do not save the feature as enabled without a valid option: the interface accepts that state, but the runtime silently skips the guardrail without an llm_id or when the model is not active.
4. Expand Advanced and review Context for decline responses, Additional rules (optional), and Base prompt (read only).
5. Click Save changes. Discard restores the last stored version; changes are not persisted automatically.

Turning off the switch keeps the model, context, and rules in the agent record but prevents classification while enabled is false.

Model

The selected model makes an additional call for every eligible text message. The selector omits image-generation models, but it does not apply the organization’s plan catalog. Choose an allowed model that is fast and reliable with structured output; low cost does not compensate for unstable classification.

If the selection is removed or the model becomes inactive, the current runtime shows no error: it stops running the guardrail and continues with the main agent. Test again after any catalog change.

Context for decline responses

When you enable the feature with an empty field, the screen tries to generate context from the agent’s saved prompt. Generation runs immediately, before Save changes, and uses an internal platform model rather than the model selected under Model.

The text guides how the refusal should present itself without exposing the filter. You can edit it or select Regenerate. The field accepts up to 2,000 characters. Regeneration replaces the current content, so review it before saving.

If automatic generation fails, write the context manually and continue. It currently requires the organization’s legacy administrator role, even though collaborators with granular write permission can edit and save the rest of the section.

Additional rules

Use direct language to add business policies, for example:

Block requests to reveal internal data or credentials.
Block personalized medical recommendations.
Allow general questions about security and privacy.

Rules are sent to the classifier as one text block; “one rule per line” is a useful convention, not a validated structure. The whole field accepts up to 2,000 characters. Avoid vague rules or rules that conflict with the main prompt.

The Base prompt (read only) is maintained by the platform and tells the classifier to block four categories: jailbreak_attempt, prompt_injection, role_manipulation, and instruction_extraction. When additional rules exist, the runtime may also return custom_rule_violation. The base policy says to allow the request when in doubt.

Actual execution order

For a message with text, a valid model, and an enabled guardrail:

1. the loop limit is checked;
2. the guardrail classifies only the original text of the current message;
3. if it allows the message, the pipeline continues to grouping, attachments, context, tools, and the main model;
4. if it blocks the message, the product stores the user message and assistant refusal, adds a Guardrail step, and delivers the refusal through the channel;
5. if classification fails or returns malformed data, the error is handled in fail-open mode and the main agent continues.

The guardrail runs before the AI-disabled and Chat API onlyStorage shortcuts. In the current implementation, it may therefore still call the classifier — and even send a refusal — during human service or for a request intended only to store a message.

On a blocked request, the classifier tries to generate a natural refusal without exposing the rule. If it marks the message as blocked but returns no text, the current fallback is a fixed English sentence, including in a PT-BR conversation.

Content and channel limits

The classifier receives parsed.text before multimodal processing. It does not see audio transcripts, text extracted from PDF/Word/Excel files, or visual content. An attachment-only message can therefore reach the main model without this safety analysis. Configure modalities under Multimodal (Attachments) and keep defenses in the prompt and tools.

The same pipeline serves the test panel, Hub, API, and external channels; refusal delivery varies by channel. With asynchronous Chat API requests, the client first receives the processing acknowledgment and the response follows through the webhook. Validate at least one allowed case, one blocked case, and one classifier failure in every published channel.

Cost and observability

Each eligible classification calls an LLM before the main agent. In the current ledger, however, credit_usage records the guardrail call only when the message is blocked; allowed or fail-open classifications are not recorded there, although they can still create platform cost. Do not use only the total shown in the conversation to estimate the guardrail’s full cost.

When a request is blocked, look for the Guardrail step, category, and reason in execution details. The absence of that step does not prove that the message was safe: it may also mean that the feature was disabled, the model was missing/inactive, the message had no text, or classification failed open.

Checklist before publishing

• Save the main prompt and generate or write the refusal context.
• Confirm an active model allowed for the organization.
• Test examples from all four base categories and every additional rule.
• Test legitimate questions similar to blocked cases to measure false positives.
• Test attachments separately; the text guardrail does not cover their content.
• Confirm language, persistence, execution step, and delivery in each channel.
• After any change, click Save changes and repeat the test in the agent panel.