Name: configuring-guardrails
Author: celigo

Configure Celigo guardrail resources -- safety and compliance checks that validate data flowing through integrations. Use when creating or editing guardrails for PII detection, content moderation, or AI-based evaluation rules.

<! TIER:1 Configuring Guardrails A guardrail is a safety and compliance check applied to data flowing through a Celigo integration. Guardrails are stored as imports with adaptorType: "GuardrailImport" and accessed via the /v1/imports API, but they have a dedicated page in the Celigo UI. Guardrails handle three concerns: Data validation check records against rules before they reach downstream systems (PII detection, content moderation, or custom AI based evaluation) Confidence tuning control sensitivity via confidenceThreshold (0 to 1, default 0.7). Lower values catch more issues but increase false positives PII masking optionally return a redacted copy of the record ( pii.mask: true ) under a masked response field. Masking is NOT automatic see [PII: mask vs flag]( pii mask vs flag) No connectionId is required unless using BYOK credentials for the ai agent type. Platform managed credentials cover most use cases. Guardrails are used across flows, APIs, and tools. Guardrail or AI agent step? Pick by what the LLM produces. A guardrail renders a verdict ( flagged: true false ) that the parent's routing branches on reach for it when the user says "verify / check / validate / flag / screen". An AI agent step does work whose output flows onward as data reach for it when the user says "classify / extract / generate / summarize / decide"; build that in [configuring ai agents](../configuring ai agents/SKILL.md). Guardrails Flag, They Don't Enforce The most important runtime semantic to internalize before designing a guardrail: a guardrail produces a verdict; it does not act on the record. Whether a flagged record gets blocked, routed to a review queue, dropped, retried, or forwarded with the verdict attached is decided by the parent's routing, branching, or filter structure the parent being a flow, an API endpoint, or a Tool not by the guardrail itself. The guardrail's job ends at "here is the structured JSON verdict"; everything downstream is the parent's responsibility. This split is deliberate. It keeps every guardrail composable across many parents (the same Customer PII Scanner can flag for review in one flow, block writes in an API endpoint, and gate a Tool's output in a third place), keeps each guardrail's contract narrow and testable, and keeps audit trails clean. A requirement like "block any records with PII" or "route flagged tickets to a Slack channel" is really two decisions: the guardrail's narrow check, and the parent's routing. Build the guardrail with its check; design the routing in the parent. Nothing the guardrail returns reaches downstream steps unless the parent authors a response mapping that extracts it. Three Types of Guardrail PII Detection Detect personally identifiable information in records. Configure which entity types to scan for (email addresses, SSNs, credit card numbers, phone numbers, etc.) and whether to mask detected values. Requires at least one entity type in guardrail.pii.entities[] . Content Moderation Check content against harmful categories (hate speech, violence, harassment, sexual content, self harm, illicit activity). Requires at least one category in guardrail.moderation.categories[] . AI Agent Evaluation Use an AI model to evaluate data against custom instructions. Configured via guardrail.aiAgent , with the same providers and config blocks as AiAgentImport (the provider enum in [aiagent.yml](references/schemas/aiagent.yml)) minus tools: a non empty tools array fails the save with 422 guardrail tools not allowed . Supports model selection, temperature, and reasoning settings; leave its output format unset (see [AI Agent: natural language rules]( ai agent natural language rules)). Unlike an agent, it gets no output cap unless you set one. Without a BYOK connection, built in providers run only the models the platform hosts, and catalog providers can't be used at all. Quick Reference Type Decision Matrix You need to... Use guardrail.type Configure Read schema Detect/mask PII (emails, SSNs, credit cards) pii guardrail.pii.entities[] , guardrail.pii.mask [guardrail.yml](references/schemas/guardrail.yml) Block harmful content (hate, violence) moderation guardrail.moderation.categories[] [guardrail.yml](references/schemas/guardrail.yml) Custom AI based validation rules ai agent guardrail.aiAgent (provider, model, instructions) [guardrail.yml](references/schemas/guardrail.yml) + [aiagent.yml](references/schemas/aiagent.yml) Minimum Required Fields Every guardrail needs: name human readable label adaptorType always "GuardrailImport" guardrail.type "pii" , "moderation" , or "ai agent" Type specific config guardrail.pii{} , guardrail.moderation{} , or guardrail.aiAgent{} No connectionId required unless using BYOK for ai agent . Schema Index All schemas are in [references/schemas/](references/schemas/): Base fields (all imports): [request.yml](references/schemas/request.yml) Response shape: [response.yml](references/schemas/response.yml) Guardrail config: [guardrail.yml](references/schemas/guardrail.yml) type, confidenceThreshold, pii, moderation AI agent config: [aiagent.yml](references/schemas/aiagent.yml) provider, model, instructions, tools, structured output (shared with AiAgentImport) Related Skills [configuring imports AI Imports](../configuring imports/SKILL.md ai imports) guardrails are a category of import; see imports for the broader context [configuring connections Quick Reference](../configuring connections/SKILL.md quick reference) BYOK connection setup for ai agent guardrails [building flows How to Build a Flow](../building flows/SKILL.md how to build a flow) wiring guardrails into flow pipelines as page processors [troubleshooting flows Diagnostic Workflow](../troubleshooting flows/SKILL.md diagnostic workflow) diagnosing guardrail related failures [configuring ai agents Quick Reference](../configuring ai agents/SKILL.md quick reference) AI agent imports share the same LLM plumbing; guardrails add safety constraints <! TIER:2 How to Build a Guardrail 1. Determine the compliance requirement What kind of check do you need? PII detection (scan for sensitive data), content moderation (block harmful content), or custom AI evaluation (apply business specific rules)? 2. Check for existing guardrails Before building from scratch, see what already exists in the account: 3. Choose the guardrail type Refer to the [Type Decision Matrix]( type decision matrix). Each type has a distinct configuration shape. 4. Configure type specific settings PII: Choose entity types to detect. Start with the most common: email address , phone number , credit card number , persons name , us social security number . Enable mask: true if downstream steps should see redacted data and plan the response mapping write back it requires (see [PII: mask vs flag]( pii mask vs flag)). Moderation: Choose categories. The core three are hate , violence , harassment . Add others as needed. AI agent: Write clear instructions for the model. Any provider in the aiAgent.provider enum works, configured as on an AI agent import see [configuring ai agents Provider Decision Matrix](../configuring ai agents/SKILL.md provider decision matrix) but with no tools . Without a BYOK connection, the model must be one the platform hosts for that provider, and the save refuses any other with 422 Model "<model " is not supported... , whose message doesn't list the hosted models. 5. Set the confidence threshold Default is 0.7. For stricter compliance, raise to 0.8 0.9. For broader detection with more false positives, lower to 0.4 0.5. Read the confidenceThreshold field in [guardrail.yml](references/schemas/guardrail.yml). 6. Build the guardrail JSON Reference the [Schema Index]( schema index). Always read [request.yml](references/schemas/request.yml) for base fields, [guardrail.yml](references/schemas/guardrail.yml) for the guardrail config, and [aiagent.yml](references/schemas/aiagent.yml) if using ai agent type. 7. Hand it over When you report the guardrail, name the field its parent routes on: flagged , true when a detection or rule fired. A guardrail only flags, so the record goes on unchanged unless a branch on flagged sends it elsewhere ([Guardrails Flag, They Don't Enforce]( guardrails flag they dont enforce)). CLI Commands Configuring Each Type in Depth pii and moderation are local deterministic classifiers the same input always produces the same output, with no LLM call, no token cost, and no model latency. ai agent is a real LLM call per record , with the cost and variance that implies. Prefer the cheaper type whenever the requirement fits; ai agent is the catch all, not the default: The three types are mutually exclusive a single guardrail cannot be both PII detection and moderation. When two orthogonal checks are needed, that is two guardrail steps in series, not one guardrail (see [Placement in the Parent Pipeline]( placement in the parent pipeline)). The choice is about what is being detected, not how the requirement is worded: a natural language description still resolves to pii when it is about PII. PII: mask vs flag After the entity list, the most tuned knob on a PII guardrail is mask : mask: false (default) detections are flagged in the verdict; the data passes through unchanged, and downstream routing decides what to do. mask: true detections are flagged AND a redacted payload is returned under a masked field on the guardrail's response. This is not automatic in place replacement the guardrail does not rewrite the in flight record. For the downstream system to receive the redacted values, the parent must author a response mapping on the guardrail step that extracts masked back onto the record. With whole record input, masked is the entire record as one JSON string, so writing it back also takes a postResponseMap hook that parses it and overwrites the original PII fields. A mask: true guardrail without that parent side write back still ships raw PII downstream. Masking one field before an AI agent sees it takes three pieces: the guardrail reads that field as its text input, its step sits before the agent's step, and the step's response mapping writes masked back over the field. The guardrail: Its flow step, listed in pageProcessors[] ahead of the agent's: The result's fields are top level: for each record a saved guardrail returns statusCode , an empty json , flagged , masked (such as "Call me back or email " ) and usage , so extract masked and flagged themselves, not json.masked . Fields the mapping doesn't select (a separate email field, say) aren't scanned or masked. Default to flag only for review style use cases where a reviewer needs to see the actual data. Default to mask: true for trust boundary use cases third party analytics, AI vendors, partner integrations, public reports where the destination should not see raw values even when the record passes. When in doubt and the destination is external, mask. The pii.entities[] enum is broad and fixed by the platform: universal entity types (email, phone, credit card, SSN, name, location, IP address, URL, and more) plus country specific identifiers across the US, UK, EU, India, Australia, Korea, Singapore, and others passport numbers only for the US, Italy and India. Map the requirement to the closest enum value (an "address" is location ) rather than switching to ai agent when a named entity is not a perfect match. Moderation: categories The moderation.categories[] enum is fixed. Top level categories are sexual , hate , harassment , self harm , violence , and illicit , e