Configuring Guardrails

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

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.

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 (OpenAI) to evaluate data against custom instructions. Configured via guardrail.aiAgent (same schema as AiAgentImport). Supports model selection, temperature, structured output, and reasoning. Without a BYOK connection, only platform-supported OpenAI models are available.

Quick Reference

Type Decision Matrix

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

• Base fields (all imports): request.yml
• Response shape: response.yml
• Guardrail config: guardrail.yml -- type, confidenceThreshold, pii, moderation
• AI agent config: aiagent.yml -- provider, model, instructions, tools, structured output (shared with AiAgentImport)

Related Skills

• configuring-imports > AI Imports -- guardrails are a category of import; see imports for the broader context
• configuring-connections > Quick Reference -- BYOK connection setup for ai_agent guardrails
• building-flows > How to Build a Flow -- wiring guardrails into flow pipelines as page processors
• troubleshooting-flows > Diagnostic Workflow -- diagnosing guardrail-related failures
• configuring-ai-agents > 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:

# List all guardrails
celigo guardrails list

# Search the account for guardrail-related resources
celigo account search "guardrail"
celigo account search "pii"
celigo account search "moderation"

3. Choose the guardrail type

Refer to the 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).
• Moderation: Choose categories. The core three are hate, violence, harassment. Add others as needed.
• AI agent: Write clear instructions for the model. Only OpenAI is supported for guardrails today. Without a BYOK connection, platform-supported OpenAI models are: gpt-5, gpt-5-pro, gpt-5-mini, gpt-5-nano, gpt-4.1, gpt-4.1-mini, gpt-4.1-nano.

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.

6. Build the guardrail JSON

Reference the Schema Index. Always read request.yml for base fields, guardrail.yml for the guardrail config, and aiagent.yml if using ai_agent type.

CLI Commands

# CRUD
celigo guardrails list
celigo guardrails get <id>
celigo guardrails create < guardrail.json
celigo guardrails update <id> < guardrail.json
celigo guardrails set <id> key=value [key2=value2 ...]
celigo guardrails delete <id> [-y]

# Invoke (test a guardrail against sample data)
echo '[{"name":"John","email":"john@example.com"}]' | celigo guardrails invoke <id>

# Clone and connection management
celigo guardrails clone <id>
celigo guardrails replace-connection <id> <newConnectionId>