references/schemas/aiagent.yml
AiAgentConfig:
type: object
description: |
AI Agent configuration used by both AiAgentImport and GuardrailImport (ai_agent type).
Configures which AI provider and model to use, along with instructions, parameter
tuning, output format, and available tools. Three providers are supported:
- **openai**: OpenAI models (GPT-4, GPT-4o, GPT-4o-mini, GPT-5, etc.). Configure via the `openai` object.
- **gemini**: Google Gemini models via the LiteLLM proxy. Configure via `litellm` with overrides in `litellm._overrides.gemini`.
- **anthropic**: Anthropic Claude models via the LiteLLM proxy. Configure via `litellm` with overrides in `litellm._overrides.anthropic`.
A `_connectionId` is optional (BYOK). If not provided on the parent import,
platform-managed credentials are used.
required: [provider]
properties:
provider:
type: string
enum: ["openai", "gemini", "anthropic"]
x-enumDescriptions:
openai: Use OpenAI models via the OpenAI Responses API.
gemini: Use Google Gemini models via the LiteLLM proxy.
anthropic: Use Anthropic Claude models via the LiteLLM proxy.
description: AI provider to use.
x-celigo-ai-guidance:
- |-
- **openai**: Uses OpenAI Responses API. Configure via the `openai` object.
- **gemini**: Uses Google Gemini via LiteLLM. Configure via `litellm` with
Gemini-specific overrides in `litellm._overrides.gemini`.
- **anthropic**: Uses Anthropic Claude via LiteLLM. Configure via `litellm` with
Claude-specific overrides in `litellm._overrides.anthropic`.
openai:
type: object
description: |
OpenAI-specific configuration. Used when `provider` is "openai".
required: [model, instructions]
properties:
instructions:
type: string
maxLength: 1000000
description: |
System prompt that defines the AI agent's behavior, goals, and constraints.
examples: ["You are a data validation agent. Check each record for completeness."]
x-celigo-ui-override: >-
Required by the AI agent configuration form (the model's system prompt). Encoded
here to mirror the form so builders produce connectable configurations.
model:
type: string
description: |-
OpenAI model identifier. Open string (not an enum) — model names change frequently.
examples: ["gpt-5.4", "gpt-5.4-pro", "gpt-5-mini", "gpt-5-nano", "gpt-4.1-mini", "gpt-4o"]
x-celigo-ui-override: >-
Required by the AI agent configuration form. Encoded here to mirror the form so
builders produce connectable configurations.
x-celigo-canon:
decision: no-enum
reason: Deliberately an open string — model names churn faster than the spec.
method: full-population
verified: '2026-07-03'
x-celigo-ai-guidance:
- |-
With platform-managed credentials (no `_connectionId` on the parent
import), the model must be on the platform's allowlist — an
unlisted model fails the save with 422. A BYOK connection bypasses
the allowlist and the model string is passed through to the
provider as-is.
reasoning:
type: object
description: |-
Controls depth of reasoning for complex tasks.
x-celigo-ai-guidance:
- |-
Supported on reasoning-capable OpenAI models only (currently the GPT-5 family and the o-series).
Setting `reasoning` on a non-reasoning model (e.g.
`gpt-4.1-mini`) is rejected by the provider at runtime — omit the field on those models.
properties:
effort:
type: string
enum: ["none", "minimal", "low", "medium", "high", "xhigh"]
x-enumDescriptions:
none: No additional reasoning effort.
minimal: Least reasoning effort for simple, straightforward tasks.
low: Light reasoning for moderately simple tasks.
medium: Balanced reasoning effort for typical tasks.
high: Maximum reasoning effort for complex, multi-step tasks.
xhigh: Highest reasoning effort for the most demanding, multi-step tasks.
description: How much reasoning effort the model should invest
x-celigo-ai-guidance:
- |-
How much reasoning effort the model should invest.
Reasoning- capable models only — see `reasoning` for the gating rule.
summary:
type: string
enum: ["concise", "auto", "detailed"]
x-enumDescriptions:
concise: Brief, high-level reasoning summary.
auto: Let the model decide the appropriate level of detail.
detailed: Comprehensive reasoning summary with full explanations.
description: Level of detail in reasoning summaries
x-celigo-ai-guidance:
- |-
Level of detail in reasoning summaries.
Reasoning-capable models only — see `reasoning` for the gating rule.
temperature:
type: number
minimum: 0
maximum: 2
description: |
Sampling temperature. Higher values (e.g. 1.5) produce more creative output,
lower values (e.g. 0.2) produce more focused and deterministic output.
topP:
type: number
minimum: 0.1
maximum: 1
description: Nucleus sampling parameter
topLogprobs:
type: number
minimum: 0
maximum: 20
description: Number of most likely tokens to return log probabilities for at each output position.
maxOutputTokens:
type: number
minimum: 100
maximum: 128000
default: 5000
description: Maximum number of tokens in the model's response (server default observed live on create)
serviceTier:
type: string
enum: ["auto", "default", "priority"]
x-enumDescriptions:
auto: Let OpenAI automatically select the appropriate service tier.
default: Standard service tier with normal rate limits and latency.
priority: Premium tier with higher rate limits and lower latency at increased cost.
default: "default"
description: |-
OpenAI service tier. "priority" provides higher rate limits and
lower latency at increased cost.
x-celigo-ai-guidance:
- |-
BYOK only.
Platform-managed credentials (no `_connectionId` on the parent import) always
run at `default` regardless of what's set here.
output:
type: object
description: Output format configuration
properties:
format:
type: object
description: |
Controls the structure of the model's output.
properties:
type:
type: string
enum: ["text", "json_schema", "blob"]
x-enumDescriptions:
text: Free-form text response from the model.
json_schema: Structured JSON output conforming to a defined schema.
blob: Binary data output for non-text content.
default: "text"
description: Output format type.
schemaMode:
type: string
enum: ["manual", "json"]
x-enumDescriptions:
manual: The schema was built field-by-field in the visual editor.
json: The schema was pasted or edited as raw JSON.
description: |-
How the structured-output schema was authored in the UI.
Editor state only — it does not change how `jsonSchema` is
sent to the provider.
name:
type: string
description: Name for the output format (used with json_schema)
x-celigo-ui-override: >-
Required by the AI agent form when output format type is json_schema. Encoded
here to mirror the form so builders produce connectable configurations.
x-celigo-canon:
decision: no-enum
reason: Free-form user-chosen format name — no vocabulary to encode.
method: full-population
verified: '2026-07-04'
strict:
type: boolean
default: false
description: When true, enforces strict schema validation on output.
x-celigo-ai-guidance:
- Whether to enforce strict schema validation on output
jsonSchema:
type: object
description: |
JSON Schema for structured output. Required when `format.type` is "json_schema".
x-celigo-ui-override: >-
Required by the AI agent form when output format type is json_schema. Encoded
here to mirror the form so builders produce connectable configurations.
properties:
type:
type: string
description: Root JSON Schema type of the structured output; use "object" for record-shaped results.
enum: ["object", "array", "string", "number", "integer", "boolean"]
x-enumDescriptions:
object: JSON object with named properties.
array: Ordered list of values.
string: Text string value.
number: Numeric value including decimals.
integer: Whole number value without decimals.
boolean: True or false value.
properties:
type: object
additionalProperties: true
description: JSON Schema definitions for each field the structured output may contain.
x-celigo-canon:
decision: no-constraint
reason: >-
User-authored JSON Schema payload — interiors are freeform by
design; do not model keys.
method: full-population
verified: '2026-07-03'
required:
type: array
description: Property names the model must include in the structured output.
items:
type: string
additionalproperties:
type: boolean
description: When true, the structured output may include properties beyond those defined in `properties`.
if:
properties:
type:
const: json_schema
required: [type]
then:
required: [name, jsonSchema]
verbose:
type: string
enum: ["low", "medium", "high"]
x-enumDescriptions:
low: Minimal detail in the model's response.
medium: Moderate detail in the model's response, the default level.
high: Maximum detail and verbosity in the model's response.
default: "medium"
description: Level of detail in the model's response
x-celigo-ai-guidance:
- |-
Supported on the GPT-5 family only. Other OpenAI models (e.g.
`gpt-4.1`, `gpt-4.1-mini`,
`gpt-4.1-nano`) accept only `medium` (the no-op default) — `low` and `high` are
rejected by the provider at runtime.
Omit the field entirely on non-GPT-5 models rather than relying on the default.
tools:
type: array
description: |
Tools available to the AI agent during processing.
items:
type: object
properties:
type:
type: string
enum: ["web_search", "mcp", "image_generation", "tool"]
x-enumDescriptions:
web_search: Search the web for real-time information.
mcp: Connect to an MCP server for additional external tools.
image_generation: Generate images using an AI image model.
tool: Reference a reusable Celigo Tool resource.
description: Type of tool.
webSearch:
type: object
description: Web search configuration (empty object to enable)
imageGeneration:
type: object
description: Image generation configuration
properties:
background:
type: string
description: Controls whether generated images have a transparent or opaque background; use transparent only with output formats that support it (png, webp).
enum: ["transparent", "opaque"]
x-enumDescriptions:
transparent: Generate an image with a transparent background.
opaque: Generate an image with a solid, non-transparent background.
quality:
type: string
description: Rendering quality of generated images, trading detail for generation speed and file size.
enum: ["low", "medium", "high"]
x-enumDescriptions:
low: Lower quality for faster generation and smaller file size.
medium: Balanced quality and generation speed.
high: Highest quality output with more detail.
size:
type: string
description: Pixel dimensions of generated images; choose square, portrait, or landscape to match the intended use.
enum: ["1024x1024", "1024x1536", "1536x1024"]
x-enumDescriptions:
1024x1024: Square image at 1024 by 1024 pixels.
1024x1536: Portrait image at 1024 by 1536 pixels.
1536x1024: Landscape image at 1536 by 1024 pixels.
outputFormat:
type: string
description: File format of generated images; use png or webp when transparency is needed.
enum: ["png", "webp", "jpeg"]
x-enumDescriptions:
png: PNG format with lossless compression, supports transparency.
webp: WebP format with efficient compression for web use.
jpeg: JPEG format with lossy compression for smaller file sizes.
mcp:
type: object
description: MCP server tool configuration
properties:
_mcpConnectionId:
type: string
format: objectId
x-celigo-refModel: connections
description: Connection to the MCP server
allowedTools:
type: array
description: |-
Specific tools to allow from the MCP server (all if
omitted). Each entry is either a plain tool name (legacy
form) or an object carrying display metadata.
items:
type: [string, object]
properties:
name:
type: string
maxLength: 256
description: Tool name as exposed by the MCP server.
title:
type: string
maxLength: 300
description: Display title shown for the tool.
description:
type: string
maxLength: 1000
description: Display description shown for the tool.
required: [name]
x-celigo-ai-guidance:
- |-
Object entries accept only name/title/description — any
other key fails validation with "unknown field(s)", and
an object without a non-empty name fails with a
missing-required-field error. String entries are the
legacy form and stay valid.
allowedPrompts:
type: array
description: Specific prompts to allow from the MCP server (used for MCP prompt entries; all if omitted).
items:
type: string
tool:
type: object
description: |
Reference to a Celigo Tool resource.
properties:
_toolId:
type: string
format: objectId
x-celigo-refModel: tools
description: Reference to the Tool resource
overrides:
type: object
description: Per-agent overrides for the tool's internal resources
properties:
connections:
type: array
description: |
Remaps the tool's abstract connections for this agent. Each entry pairs
the tool's abstract connection placeholder (`_abstractId`) with the
concrete connection (`_id`) to use for this agent; entries without
`_id` keep the tool's own default connection.
items:
type: [object, 'null']
required: [_abstractId]
properties:
_abstractId:
type: string
format: objectId
description: The tool's abstract connection placeholder being overridden.
_id:
type: string
format: objectId
x-celigo-refModel: connections
description: Concrete connection to use in place of the abstract placeholder.
prompts:
type: array
description: |
MCP prompt entries available to the agent. Each item references one MCP connection
and the prompt names allowed from it. Configured alongside `tools` in the form but
stored separately; an entry's `allowedPrompts` is what distinguishes a prompt entry
from an MCP tool entry (which carries `allowedTools`).
items:
type: object
properties:
type:
type: string
enum: ["mcp"]
x-enumDescriptions:
mcp: Connect to an MCP server to use its exposed prompts.
description: Type of prompt entry. Always "mcp".
mcp:
type: object
description: MCP server prompt configuration.
properties:
_mcpConnectionId:
type: string
format: objectId
x-celigo-refModel: connections
description: Connection to the MCP server.
allowedPrompts:
type: array
description: Prompt names to allow from the MCP server.
items:
type: string
resources:
$ref: '#/McpResources'
litellm:
type: object
description: |
LiteLLM proxy configuration. Used when `provider` is "gemini" or "anthropic".
LiteLLM provides a unified interface to multiple AI providers. Gemini-specific
settings are in `_overrides.gemini`; Claude-specific settings are in
`_overrides.anthropic`.
`model` is required when litellm is the active provider path.
properties:
model:
type: string
description: |-
LiteLLM model identifier. For Gemini, models are stored without the `gemini/`
prefix; for Anthropic, use the Claude model id (e.g. `claude-sonnet-4-6`).
examples: ["gemini-2.5-flash", "gemini-2.5-pro", "gemini-2.5-flash-lite", "claude-sonnet-4-6", "claude-opus-4-7"]
x-celigo-canon:
decision: no-enum
reason: Deliberately an open string — model names churn faster than the spec.
method: full-population
verified: '2026-07-03'
x-celigo-ui-override: >-
Required by the AI agent configuration form. Encoded here to mirror the form so
builders produce connectable configurations.
temperature:
type: number
minimum: 0
maximum: 2
description: Sampling temperature
x-celigo-ai-guidance:
- |-
When `provider` is "anthropic", the value must be between 0 and 1 — a higher value
fails the save with 422 `invalid_field_value`. Gemini accepts the full 0-2 range.
maxCompletionTokens:
type: number
minimum: 100
maximum: 128000
default: 5000
description: Maximum number of tokens in the response
topP:
type: number
minimum: 0.1
maximum: 1
description: Nucleus sampling parameter
seed:
type: number
description: Random seed for reproducible outputs
responseFormat:
type: object
description: Output format configuration
x-celigo-ai-guidance:
- |-
When `provider` is "anthropic", `type` must be "text" or "json_schema" — "blob" is
rejected with 422 `invalid_response_format`. As with the other providers, "json_schema"
requires `name` and `jsonSchema`.
properties:
type:
type: string
description: Output format type.
enum: ["text", "json_schema", "blob"]
x-enumDescriptions:
text: Free-form text response from the model.
json_schema: Structured JSON output conforming to a defined schema.
blob: Binary data output for non-text content.
default: "text"
schemaMode:
type: string
enum: ["manual", "json"]
x-enumDescriptions:
manual: The schema was built field-by-field in the visual editor.
json: The schema was pasted or edited as raw JSON.
description: |-
How the structured-output schema was authored in the UI. Editor
state only — it does not change how `jsonSchema` is sent to the
provider.
name:
type: string
description: Name for the output format (used with json_schema).
x-celigo-ui-override: >-
Required by the AI agent form when output format type is json_schema. Encoded
here to mirror the form so builders produce connectable configurations.
strict:
type: boolean
description: When true, enforces strict schema validation on output.
default: false
jsonSchema:
type: object
description: JSON Schema for structured output. Required when `responseFormat.type` is "json_schema".
x-celigo-ui-override: >-
Required by the AI agent form when output format type is json_schema. Encoded
here to mirror the form so builders produce connectable configurations.
properties:
type:
type: string
description: Root JSON Schema type of the structured output; use "object" for record-shaped results.
enum: ["object", "array", "string", "number", "integer", "boolean"]
x-enumDescriptions:
object: JSON object with named properties.
array: Ordered list of values.
string: Text string value.
number: Numeric value including decimals.
integer: Whole number value without decimals.
boolean: True or false value.
properties:
type: object
additionalProperties: true
description: JSON Schema definitions for each field the structured output may contain.
required:
type: array
description: Property names the model must include in the structured output.
items:
type: string
additionalProperties:
type: boolean
description: When true, the structured output may include properties beyond those defined in `properties`.
if:
properties:
type:
const: json_schema
required: [type]
then:
required: [name, jsonSchema]
_overrides:
type: object
description: Provider-specific overrides
properties:
gemini:
type: object
description: |
Gemini-specific configuration overrides.
required: [systemInstruction]
properties:
systemInstruction:
type: string
maxLength: 1000000
description: |
System instruction for Gemini models. Equivalent to OpenAI's `instructions`.
Maximum 1,000,000 characters.
x-celigo-ui-override: >-
Required by the AI agent configuration form (the model's system prompt, the
Gemini equivalent of `instructions`). Encoded here to mirror the form so
builders produce connectable configurations.
tools:
type: array
description: Gemini-specific tools
items:
type: object
properties:
type:
type: string
enum: ["googleSearch", "urlContext", "fileSearch", "mcp", "tool"]
x-enumDescriptions:
googleSearch: Use Google Search for real-time information grounding.
urlContext: Retrieve and use content from specified URLs.
fileSearch: Search through previously uploaded files.
mcp: Connect to an MCP server for additional external tools.
tool: Reference a reusable Celigo Tool resource.
description: Type of Gemini tool.
googleSearch:
type: object
description: Google Search configuration (empty object to enable)
urlContext:
type: object
description: URL context configuration (empty object to enable)
fileSearch:
type: object
description: File search configuration, used when type is "fileSearch".
properties:
fileSearchStoreNames:
type: array
description: Names of the file search stores the model can query.
items:
type: string
mcp:
type: object
description: MCP server tool configuration, used when type is "mcp".
properties:
_mcpConnectionId:
type: string
format: objectId
x-celigo-refModel: connections
description: Connection to the MCP server.
allowedTools:
type: array
description: |-
Specific tools to allow from the MCP server (all if
omitted). Each entry is either a plain tool name
(legacy form) or an object carrying display metadata
— same contract as the OpenAI `allowedTools`.
items:
type: [string, object]
properties:
name:
type: string
maxLength: 256
description: Tool name as exposed by the MCP server.
title:
type: string
maxLength: 300
description: Display title shown for the tool.
description:
type: string
maxLength: 1000
description: Display description shown for the tool.
required: [name]
allowedPrompts:
type: array
description: Specific prompts to allow from the MCP server (used for MCP prompt entries; all if omitted).
items:
type: string
tool:
type: object
description: Reference to a Celigo Tool resource, used when type is "tool".
properties:
_toolId:
type: string
format: objectId
x-celigo-refModel: tools
description: Reference to the Tool resource.
overrides:
type: object
description: Per-agent overrides for the tool's internal resources.
properties:
connections:
type: array
description: |
Remaps the tool's abstract connections for this agent. Each entry
pairs the tool's abstract connection placeholder (`_abstractId`)
with the concrete connection (`_id`) to use for this agent;
entries without `_id` keep the tool's own default connection.
items:
type: [object, 'null']
required: [_abstractId]
properties:
_abstractId:
type: string
format: objectId
description: The tool's abstract connection placeholder being overridden.
_id:
type: string
format: objectId
x-celigo-refModel: connections
description: Concrete connection to use in place of the abstract placeholder.
prompts:
type: array
description: |
MCP prompt entries available to the Gemini agent. Each item references one
MCP connection and the prompt names allowed from it. The presence of
`allowedPrompts` distinguishes a prompt entry from an MCP tool entry.
items:
type: object
properties:
type:
type: string
enum: ["mcp"]
x-enumDescriptions:
mcp: Connect to an MCP server to use its exposed prompts.
description: Type of prompt entry. Always "mcp".
mcp:
type: object
description: MCP server prompt configuration.
properties:
_mcpConnectionId:
type: string
format: objectId
x-celigo-refModel: connections
description: Connection to the MCP server.
allowedPrompts:
type: array
description: Prompt names to allow from the MCP server.
items:
type: string
resources:
$ref: '#/McpResources'
responseModalities:
type: array
description: Response output modalities
x-celigo-ai-guidance:
- |-
`["image"]` requires an image-capable Gemini model (currently `gemini-2.5-flash-image`).
Selecting it on a text-only model is rejected by the provider — pair image
output with the right model or omit.
items:
type: string
enum: ["text", "image"]
x-enumDescriptions:
text: Generate text content in the response.
image: Generate image content in the response.
default: ["text"]
topK:
type: number
description: Top-K sampling parameter for Gemini
thinkingConfig:
type: object
description: Controls Gemini's extended thinking capabilities
x-celigo-ai-guidance:
- |-
Supported on reasoning-capable Gemini models only (currently `gemini-2.5-pro`
and `gemini-2.5-flash`).
Setting `thinkingConfig` on a non-thinking model (e.g.
`gemini-2.5-flash-lite`,
`gemini-2.5-flash-image`) is rejected by the provider at runtime — omit the
field on those models.
properties:
includeThoughts:
type: boolean
description: When true, includes the model's thinking steps in the response.
x-celigo-ai-guidance:
- Whether to include thinking steps in the response
thinkingBudget:
type: number
minimum: 100
maximum: 4000
description: Maximum tokens allocated for thinking
thinkingLevel:
type: string
description: Controls how much thinking effort the model applies; use higher levels for complex, multi-step tasks at the cost of latency and tokens.
enum: ["minimal", "low", "medium", "high"]
x-enumDescriptions:
minimal: Least thinking effort for simple tasks.
low: Light thinking for moderately simple tasks.
medium: Balanced thinking effort for typical tasks.
high: Maximum thinking effort for complex, multi-step tasks.
imageConfig:
type: object
description: Gemini image generation configuration
properties:
aspectRatio:
type: string
description: Aspect ratio of generated images; choose a ratio matching the intended display format.
enum: ["1:1", "2:3", "3:2", "3:4", "4:3", "4:5", "5:4", "9:16", "16:9", "21:9"]
x-enumDescriptions:
"1:1": Square aspect ratio.
"2:3": Portrait aspect ratio (2 wide by 3 tall).
"3:2": Landscape aspect ratio (3 wide by 2 tall).
"3:4": Portrait aspect ratio (3 wide by 4 tall).
"4:3": Standard landscape aspect ratio (4 wide by 3 tall).
"4:5": Portrait aspect ratio (4 wide by 5 tall).
"5:4": Landscape aspect ratio (5 wide by 4 tall).
"9:16": Tall portrait aspect ratio for mobile screens.
"16:9": Widescreen landscape aspect ratio.
"21:9": Ultra-widescreen cinematic aspect ratio.
imageSize:
type: string
description: Output resolution of generated images; higher resolutions increase detail and file size.
enum: ["1K", "2K", "4K"]
x-enumDescriptions:
"1K": Standard resolution output around 1024 pixels.
"2K": High resolution output around 2048 pixels.
"4K": Ultra-high resolution output around 4096 pixels.
mediaResolution:
type: string
enum: ["low", "medium", "high"]
x-enumDescriptions:
low: Low resolution for faster processing and reduced token usage.
medium: Balanced resolution for typical media processing.
high: High resolution for maximum detail in media inputs.
description: Resolution for media inputs (images, video)
anthropic:
type: object
description: |
Claude-specific configuration overrides. Used when `provider` is "anthropic".
required: [systemInstruction]
properties:
systemInstruction:
type: string
maxLength: 1000000
description: |
System instruction for Claude models. Equivalent to OpenAI's `instructions`.
Maximum 1,000,000 characters.
x-celigo-ui-override: >-
Required by the AI agent configuration form (the model's system prompt, the
Claude equivalent of `instructions`). Encoded here to mirror the form so
builders produce connectable configurations.
topK:
type: number
minimum: 0
description: |-
Top-K sampling parameter. Deprecated on Claude models released after Claude Opus
4.6, which reject any value at runtime; set it only on older models.
thinkingConfig:
type: object
description: Controls Claude's extended thinking capabilities.
properties:
type:
type: string
enum: ["enabled", "disabled", "adaptive"]
x-enumDescriptions:
enabled: Turn on extended thinking with an explicit token budget.
disabled: Turn off extended thinking.
adaptive: Let the model decide how much to think based on task complexity.
default: "disabled"
description: Extended thinking mode.
budgetTokens:
type: number
minimum: 1024
description: |-
Maximum tokens allocated for thinking. Required when `type` is "enabled" —
omitting it fails the save with 422 `invalid_thinking_config`.
x-celigo-ui-override: >-
Required by the AI agent form when thinkingConfig.type is "enabled". Encoded
here to mirror the form so builders produce connectable configurations.
display:
type: string
enum: ["summarized", "omitted"]
x-enumDescriptions:
summarized: Include a summarized view of the model's thinking in the response.
omitted: Exclude the model's thinking from the response.
default: "summarized"
description: How thinking output is surfaced in the response.
effort:
type: string
enum: ["low", "medium", "high", "xhigh", "max"]
x-enumDescriptions:
low: Light thinking effort for moderately simple tasks.
medium: Balanced thinking effort for typical tasks.
high: Maximum standard thinking effort for complex tasks.
xhigh: Extended thinking effort beyond high for demanding tasks.
max: Highest available thinking effort.
description: |-
How much thinking effort the model applies; use with `type` "adaptive". Higher
values (`xhigh`, `max`) may be gated to specific Claude models by the provider.
if:
properties:
type:
const: enabled
required: [type]
then:
required: [budgetTokens]
serviceTier:
type: string
enum: ["auto", "standard_only"]
x-enumDescriptions:
auto: Let Anthropic select the appropriate service tier.
standard_only: Restrict processing to the standard service tier.
default: "auto"
description: Anthropic service tier for the request.
tools:
type: array
description: Claude-specific tools.
items:
type: object
properties:
type:
type: string
enum: ["tool", "mcp", "webSearch"]
x-enumDescriptions:
tool: Reference a reusable Celigo Tool resource.
mcp: Connect to an MCP server for additional external tools.
webSearch: Search the web for real-time information.
description: Type of Claude tool.
tool:
type: object
description: Reference to a Celigo Tool resource, used when type is "tool".
properties:
_toolId:
type: string
format: objectId
x-celigo-refModel: tools
description: Reference to the Tool resource.
overrides:
type: object
description: Per-agent overrides for the tool's internal resources.
properties:
connections:
type: array
description: |
Remaps the tool's abstract connections for this agent. Each entry
pairs the tool's abstract connection placeholder (`_abstractId`)
with the concrete connection (`_id`) to use for this agent;
entries without `_id` keep the tool's own default connection.
items:
type: [object, 'null']
required: [_abstractId]
properties:
_abstractId:
type: string
format: objectId
description: The tool's abstract connection placeholder being overridden.
_id:
type: string
format: objectId
x-celigo-refModel: connections
description: Concrete connection to use in place of the abstract placeholder.
mcp:
type: object
description: MCP server tool configuration, used when type is "mcp".
properties:
_mcpConnectionId:
type: string
format: objectId
x-celigo-refModel: connections
description: Connection to the MCP server.
allowedTools:
type: array
description: Specific tools to allow from the MCP server (all if omitted).
items:
type: string
webSearch:
type: object
description: Web search configuration, used when type is "webSearch".
x-celigo-ai-guidance:
- |-
`allowedDomains` and `blockedDomains` are mutually exclusive — set at most
one. Sending both fails with 422 `invalid_hosted_tool`.
- |-
When `userLocation` is present, set at least one of `city`, `country`,
`region`, or `timezone`; an empty `userLocation` fails with 422
`missing_required_field`.
properties:
version:
type: string
pattern: "^\\d{8}$"
description: |-
Anthropic web search tool version (YYYYMMDD). Selects the tool version sent
on the wire; unsupported versions surface as an Anthropic 400.
examples: ["20250305"]
allowedDomains:
type: array
description: Domains the search may return results from. Mutually exclusive with `blockedDomains`.
items:
type: string
blockedDomains:
type: array
description: Domains to exclude from search results. Mutually exclusive with `allowedDomains`.
items:
type: string
userLocation:
type: object
description: |-
Approximate user location used to localize search results. When present, at
least one of `city`, `country`, `region`, or `timezone` must be set.
properties:
type:
type: string
enum: ["approximate"]
x-enumDescriptions:
approximate: Localize results to an approximate user location.
description: Location type. Always "approximate".
city:
type: string
maxLength: 256
description: City name for localizing search results.
country:
type: string
maxLength: 8
description: ISO 3166-1 alpha-2 country code for localizing search results.
region:
type: string
maxLength: 256
description: Region or state for localizing search results.
timezone:
type: string
maxLength: 64
description: IANA timezone for localizing search results.
prompts:
type: array
description: |
MCP prompt entries available to the Claude agent. Each item references one MCP
connection and the prompt names allowed from it. The presence of `allowedPrompts`
distinguishes a prompt entry from an MCP tool entry.
items:
type: object
properties:
type:
type: string
enum: ["mcp"]
x-enumDescriptions:
mcp: Connect to an MCP server to use its exposed prompts.
description: Type of prompt entry. Always "mcp".
mcp:
type: object
description: MCP server prompt configuration.
properties:
_mcpConnectionId:
type: string
format: objectId
x-celigo-refModel: connections
description: Connection to the MCP server.
allowedPrompts:
type: array
description: Prompt names to allow from the MCP server.
items:
type: string
resources:
$ref: '#/McpResources'
# Instance-level `required: [openai|litellm]` is what actually forces the provider
# block to exist — nesting requireds under `properties` alone does not (a bare
# `{provider: openai}` would validate). The server 422s
# ("`model` is required for AI Agent import") when the block is missing. `model` is
# server-required; `instructions` is a form-mirror (server accepts its omission — see
# the x-celigo-ui-override on that field).
if:
properties:
provider:
const: openai
required: [provider]
then:
required: [openai]
properties:
openai:
required: [model, instructions]
else:
if:
properties:
provider:
enum: [gemini, anthropic]
required: [provider]
then:
required: [litellm]
properties:
litellm:
required: [model]
McpResources:
type: array
description: |-
Governed MCP resources — read-only reference content (policies, schemas, documentation)
pulled from connected MCP servers and made available to the agent as a consistent source
of truth. Each entry references one MCP connection and the specific resources allowed from it.
items:
type: object
required: [type, mcp]
properties:
type:
type: string
enum: ["mcp"]
x-enumDescriptions:
mcp: Reference read-only resources exposed by an MCP server.
description: Type of resource entry. Always "mcp".
mcp:
type: object
required: [_mcpConnectionId, allowedResources]
description: MCP server resource configuration.
properties:
_mcpConnectionId:
type: string
format: objectId
x-celigo-refModel: connections
description: Connection to the MCP server that exposes the resources.
allowedResources:
type: array
minItems: 1
description: |-
Resources to expose to the agent from the MCP server. Must contain at least one
entry; each entry identifies one resource by name and URI.
items:
type: object
required: [name, uri]
properties:
name:
type: string
description: Display name of the MCP resource.
examples: ["Data Retention Policy"]
uri:
type: string
description: URI that identifies the resource on the MCP server.
examples: ["resource://policies/data-retention"]
references/schemas/guardrail.yml
GuardrailConfig:
type: object
description: |-
Configuration for GuardrailImport adaptor type.
Guardrails evaluate data flowing through integrations for safety and
compliance. The `type` field selects which check to apply, and the
corresponding sub-object (`aiAgent`, `pii`, or `moderation`) provides
the configuration.
A `_connectionId` on the parent import is only needed for BYOK
`ai_agent` guardrails. In responses the server echoes the active type's
sub-object and applies the `confidenceThreshold` default; it also
returns inactive sibling sub-objects (e.g. `moderation: {categories: []}`
on a `pii` guardrail, or a populated `pii` left over from a type switch),
but only the active type's sub-object is meaningful. Legacy documents
may carry a server-written default `aiAgent` stub on `pii`/`moderation`
guardrails; current servers strip the inactive `aiAgent` on write.
x-celigo-ai-guidance:
- |-
Guardrails are safety and compliance checks that can be applied
to data flowing through integrations. Three mutually-exclusive
types are supported — see `type` below for the full decision
rule on which to pick:
- **pii**: Detect (and optionally mask) personally identifiable
information. Local deterministic classifier; fixed enum of
entity types (`pii.entities`).
- **moderation**: Detect harmful / inappropriate / policy-
violating CONTENT. Local deterministic classifier; fixed enum
of categories (`moderation.categories` — `sexual`, `hate`,
`harassment`, `self_harm`, `violence`, `illicit`, etc.). Use
category names exactly as listed in the enum — e.g. `hate`
(not "hate speech"), `violence` (not "violent content"). Map
natural-language synonyms ("explicit" → `sexual`, "toxic" →
`harassment`, etc.) to the closest enum value rather than
falling back to `ai_agent`.
- **ai_agent**: LLM-evaluated judgement against custom
instructions. Catch-all for intents that don't fit `pii` or
`moderation` — domain-specific compliance, business-policy
checks, data-quality assertions, etc. Pick this LAST, not as
the default.
- |-
Prefer the cheaper / more deterministic types (`pii` > `moderation` >
`ai_agent`) whenever the brief's intent fits.
- Guardrail imports do not require a `_connectionId` (unless using BYOK for `ai_agent` type).
properties:
type:
type: string
enum: ["ai_agent", "pii", "moderation"]
x-enumDescriptions:
ai_agent: Evaluate data using an AI model with custom instructions.
pii: Detect personally identifiable information in data fields.
moderation: Check content for harmful or inappropriate categories.
description: |-
The type of guardrail to apply. Each type requires its corresponding
sub-configuration object (`aiAgent`, `pii`, or `moderation`).
x-celigo-ai-guidance:
- |-
The type of guardrail to apply.
Pick exactly one — `pii` / `moderation` / `ai_agent` are mutually exclusive at
the type level (a brief that wants both runs as two guardrails in sequence,
not one).
- |-
## How to choose
Apply these rules **in order** and pick the first match. Do
NOT skip ahead to `ai_agent` just because the brief is in
natural language — `pii` and `moderation` are also expressed
as natural-language briefs. The decision is about WHAT the
brief asks the guardrail to detect, not how the brief is
worded.
1. **`pii`** — pick this when the brief names ANY personally
identifiable information, OR when the brief names entity
categories (SSN, email, phone, credit card, address, name,
passport, license, account number, etc.) that match
`pii.entities`. Examples that route here:
"detect SSN and credit card numbers", "mask customer
emails and phone numbers", "scan for PII".
2. **`moderation`** — pick this when the brief asks the
guardrail to detect harmful, inappropriate, unsafe, or
policy-violating CONTENT (as opposed to PII data fields)
AND the intent maps to any value in `moderation.categories`
(`sexual`, `hate`, `harassment`, `self_harm`, `violence`,
`illicit`, etc.) — including via close synonyms. Apply
the synonym mapping liberally:
- "explicit", "obscene", "vulgar", "profane",
"inappropriate language", "swearing", "NSFW" → typically
maps to `sexual` and/or `harassment`
- "abusive", "insulting", "bullying", "toxic" → `harassment`
- "hateful", "discriminatory", "racist", "sexist" → `hate`
- "threatening", "intimidating" → `harassment_threatening`
or `violence`
- "graphic violence", "gore" → `violence_graphic`
- "suicide", "self-injury" → `self_harm`
- "drugs", "weapons", "illegal activity" → `illicit`
Briefs like "screen email body for explicit language",
"block toxic chat messages", "flag harassment in support
tickets", "moderate user-generated content for unsafe
material" all route to `moderation`. When the brief uses
a synonym, populate `moderation.categories` with the
closest enum value(s) — do NOT invent new category
strings; the enum is fixed.
3. **`ai_agent`** — pick this ONLY when the brief asks for
judgement that doesn't fit `pii` or `moderation`. Typical
triggers: domain-specific compliance checks (HIPAA / SOX
rule evaluation), business-policy validation (price
bounds, approval thresholds), data-quality assertions
(required fields populated, values plausible), or any
"evaluate against these custom rules" framing where the
rules are domain-specific and have no `pii.entities` /
`moderation.categories` analogue. If you can map the
brief's intent to a moderation category (even via a
synonym above), use `moderation` instead — `ai_agent` is
the catch-all, not the default.
Tie-breaker for borderline cases: prefer the more specific
type (`pii` > `moderation` > `ai_agent`). `pii` and
`moderation` are local deterministic classifiers with fixed
enums — they're cheaper, faster, and more predictable than
`ai_agent` (which calls a real LLM per record). Default to
the cheaper path whenever the intent fits.
- |-
## Sub-configuration requirements (one per type)
- **ai_agent** requires the `aiAgent` sub-configuration.
- **pii** requires the `pii` sub-configuration with at least
one entity from `pii.entities`.
- **moderation** requires the `moderation` sub-configuration
with at least one category from `moderation.categories`.
confidenceThreshold:
type: number
minimum: 0
maximum: 1
default: 0.7
x-celigo-ui-override: >-
Required by the guardrail form (confidenceThreshold is required:true once a type is
selected, default 0.7). Encoded to mirror the form so builders produce connectable
configurations.
x-celigo-canon:
decision: stricter-than-server
reason: >-
Required as a documented form mirror (with the form default) — the API itself
defaults it on write; kept so builders produce connectable configurations.
method: documented-contract
verified: '2026-07-04'
description: |-
Confidence threshold (0 to 1). Detections below this threshold are
ignored. Lower values catch more issues but increase false positives.
x-celigo-ai-guidance:
- Confidence threshold for guardrail detection (0 to 1).
- |-
Only detections with confidence at or above this threshold will be flagged.
Lower values catch more potential issues but may increase false positives.
examples: [0.7, 0.5, 0.9]
aiAgent:
type: object
description: |-
AI agent check configuration; set when `type` is `ai_agent`. On
`pii`/`moderation` guardrails a legacy server-written stub may
appear here — it is inert, and current servers strip it on write.
pii:
type: object
required: [entities]
description: |-
PII detection configuration. Required when `type` is `pii`.
x-celigo-ai-guidance:
- Configuration for PII (Personally Identifiable Information) detection.
- |-
Required when `guardrail.type` is "pii".
At least one entity type must be specified.
properties:
entities:
type: array
description: |-
PII entity types to detect. When `type` is `pii`, at least one
entry is required; the inactive sibling on other guardrail types
may be served with an empty list.
x-celigo-ai-guidance:
- PII entity types to detect in the data.
- At least one entity must be specified when using PII guardrails.
items:
type: string
enum:
- credit_card_number
- card_security_code_cvv_cvc
- cryptocurrency_wallet_address
- date_and_time
- email_address
- iban_code
- bic_swift_bank_identifier_code
- ip_address
- location
- medical_license_number
- national_registration_number
- persons_name
- phone_number
- url
- us_bank_account_number
- us_drivers_license
- us_itin
- us_passport_number
- us_social_security_number
- uk_nhs_number
- uk_national_insurance_number
- spanish_nif
- spanish_nie
- italian_fiscal_code
- italian_drivers_license
- italian_vat_code
- italian_passport
- italian_identity_card
- polish_pesel
- finnish_personal_identity_code
- singapore_nric_fin
- singapore_uen
- australian_abn
- australian_acn
- australian_tfn
- australian_medicare
- indian_pan
- indian_aadhaar
- indian_vehicle_registration
- indian_voter_id
- indian_passport
- korean_resident_registration_number
x-enumDescriptions:
credit_card_number: Credit or debit card number (e.g., Visa, Mastercard, Amex).
card_security_code_cvv_cvc: Card security code printed on credit or debit cards (CVV/CVC).
cryptocurrency_wallet_address: Cryptocurrency wallet address (e.g., Bitcoin, Ethereum).
date_and_time: Date and/or time values that could identify an individual.
email_address: Email address in standard format.
iban_code: International Bank Account Number used for cross-border payments.
bic_swift_bank_identifier_code: BIC/SWIFT code identifying a specific bank for international transfers.
ip_address: IPv4 or IPv6 network address.
location: Physical location or geographic coordinates.
medical_license_number: Medical professional license or registration number.
national_registration_number: National identification or registration number.
persons_name: Full or partial name of a person.
phone_number: Telephone number in any format.
url: Web URL or URI.
us_bank_account_number: United States bank account number.
us_drivers_license: United States driver's license number.
us_itin: United States Individual Taxpayer Identification Number.
us_passport_number: United States passport number.
us_social_security_number: United States Social Security Number (SSN).
uk_nhs_number: United Kingdom National Health Service number.
uk_national_insurance_number: United Kingdom National Insurance number.
spanish_nif: Spanish tax identification number (NIF).
spanish_nie: Spanish foreigner identification number (NIE).
italian_fiscal_code: Italian fiscal code (Codice Fiscale).
italian_drivers_license: Italian driver's license number.
italian_vat_code: Italian VAT identification number (Partita IVA).
italian_passport: Italian passport number.
italian_identity_card: Italian national identity card number.
polish_pesel: Polish national identification number (PESEL).
finnish_personal_identity_code: Finnish personal identity code (henkilotunnus).
singapore_nric_fin: Singapore National Registration Identity Card or Foreign Identification Number.
singapore_uen: Singapore Unique Entity Number for business registration.
australian_abn: Australian Business Number.
australian_acn: Australian Company Number.
australian_tfn: Australian Tax File Number.
australian_medicare: Australian Medicare card number.
indian_pan: Indian Permanent Account Number for tax purposes.
indian_aadhaar: Indian Aadhaar unique identity number.
indian_vehicle_registration: Indian vehicle registration number.
indian_voter_id: Indian voter identification card number.
indian_passport: Indian passport number.
korean_resident_registration_number: South Korean resident registration number.
examples:
- ["email_address", "phone_number", "persons_name"]
- ["us_social_security_number", "credit_card_number"]
x-celigo-canon:
decision: verified-exact
reason: >-
Item enum is server-enforced — a bogus entity is hard-rejected with a Mongoose
enum error and the full population contains zero out-of-enum values.
method: live-probe
verified: '2026-07-04'
mask:
type: boolean
default: false
description: |-
When true, detected PII is replaced with masked values.
When false, PII is flagged without modification.
x-celigo-ai-guidance:
- Whether to mask detected PII values in the output.
x-celigo-canon:
decision: not-required
reason: >-
Server defaults the value on write — universal presence on recent docs is the
server default; requiring it would reject valid creates.
method: live-probe
verified: '2026-07-04'
moderation:
type: object
required: [categories]
description: |-
Content moderation configuration. Required when `type` is `moderation`.
x-celigo-ai-guidance:
- |-
Required when `guardrail.type` is "moderation".
At least one category must be specified.
properties:
categories:
type: array
description: |-
Content moderation categories to check. When `type` is
`moderation`, at least one entry is required; the inactive
sibling on other guardrail types may be served with an empty
list.
x-celigo-ai-guidance:
- At least one category must be specified when using moderation guardrails.
items:
type: string
enum:
- sexual
- sexual_minors
- hate
- hate_threatening
- harassment
- harassment_threatening
- self_harm
- self_harm_intent
- self_harm_instructions
- violence
- violence_graphic
- illicit
- illicit_violent
x-enumDescriptions:
sexual: Content depicting sexual activity or explicit sexual material.
sexual_minors: Sexual content involving minors.
hate: Content expressing hatred toward a group based on protected characteristics.
hate_threatening: Hateful content that includes threats of violence or serious harm.
harassment: Content that targets, intimidates, or bullies an individual.
harassment_threatening: Harassment content that includes threats of violence or serious harm.
self_harm: Content that promotes or depicts self-harm behaviors.
self_harm_intent: Content expressing intent to engage in self-harm.
self_harm_instructions: Content providing instructions for self-harm methods.
violence: Content depicting or promoting physical violence.
violence_graphic: Graphic or gory depictions of violence or injury.
illicit: Content promoting illegal activities or unlawful behavior.
illicit_violent: Content promoting illegal activities that involve violence.
examples:
- ["hate", "violence", "harassment"]
- ["sexual", "self_harm", "illicit"]
x-celigo-canon:
decision: verified-exact
reason: >-
Item enum is server-enforced — a bogus category is hard-rejected with a
Mongoose enum error and the full population contains zero out-of-enum values.
method: live-probe
verified: '2026-07-04'
required:
- type
- confidenceThreshold
if:
required: [type]
properties:
type:
const: pii
then:
required: [pii]
properties:
pii:
required: [entities]
properties:
entities:
minItems: 1
else:
if:
required: [type]
properties:
type:
const: moderation
then:
required: [moderation]
properties:
moderation:
required: [categories]
properties:
categories:
minItems: 1
else:
required: [aiAgent]
properties:
aiAgent:
$ref: "./aiagent.yml#/AiAgentConfig"
references/schemas/request.yml
Request:
type: object
description: |-
Fields that can be sent when creating or updating an import. Set the adaptor-specific
configuration object matching `adaptorType` (e.g. `netsuite_da` for `NetSuiteDistributedImport`).
`_connectionId` is required except for the connection-less flavors (`ToolImport`,
`AiAgentImport`, `GuardrailImport`): a `ToolImport` binds connections through the
referenced tool's `overrides`, and AI agent / guardrail imports only use a connection
for BYOK.
required:
- name
allOf:
- $ref: './base.yml#/ImportBase'
# _connectionId is waived for the connection-less flavors, recognized either by an explicit
# adaptorType or by the presence of the flavor's config subdoc (the server infers the
# adaptorType from that subdoc when it is omitted). Every other import still requires it.
if:
anyOf:
- required: [adaptorType]
properties:
adaptorType:
enum: [ToolImport, AiAgentImport, GuardrailImport]
- required: [tool]
- required: [aiAgent]
- required: [guardrail]
else:
required: [_connectionId]
references/schemas/response.yml
Import:
type: object
required:
- _id
- name
- adaptorType
- apiIdentifier
- createdAt
- lastModified
description: Import object as returned by the API.
allOf:
- $ref: './base.yml#/ImportBase'
- $ref: '../../../common/schemas/resource-response.yml#/ResourceResponse'
- $ref: '../../../common/schemas/ia-resource-response.yml#/IAResourceResponse'
- type: object
properties:
aiDescription:
$ref: '../../../common/schemas/ai-description.yml#/AIDescription'
apim:
$ref: '../../../common/schemas/apim.yml#/APIM'
apiIdentifier:
type: string
readOnly: true
description: API identifier assigned to this import.
sandbox:
type: boolean
deprecated: true
readOnly: true
description: When true, this import belongs to a sandbox account.
rest:
type: object
deprecated: true
readOnly: true
additionalProperties: true
description: |-
Legacy REST adaptor configuration, still returned on imports created before
the REST-to-HTTP migration (`adaptorType: RESTImport`). Mirrors the shape of
`http` with per-operation arrays (`method`, `relativeURI`, `body`,
`responseIdPath`). On write the platform maintains the equivalent `http`
configuration — configure new imports through `http` instead.
_sourceId:
type: string
format: objectId
readOnly: true
description: Reference to the source resource this import was created from.
_templateId:
type: string
format: objectId
readOnly: true
x-celigo-refModel: templates
description: Template this import was created from.
draft:
type: boolean
readOnly: true
description: When true, this import is in draft state and has not been confirmed.
draftExpiresAt:
type: string
format: date-time
readOnly: true
description: Timestamp when the draft version of this import expires.
debugUntil:
type: string
format: date-time
readOnly: true
description: Timestamp until which debug logging is enabled for this import.
SKILL.md
---
name: configuring-guardrails
description: 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.
## 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
| 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:
```bash
# 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](#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. 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](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.
## CLI Commands
```bash
# 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>
# Discovery
celigo guardrails list
celigo account search "guardrail"
# Debug
celigo guardrails enable-debug <id> [--duration <minutes>]
celigo guardrails disable-debug <id>
```
## 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:
```
pii > moderation > ai_agent
```
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, and, for record-mode masking, a `postResponseMap` hook that overwrites the original PII fields with the masked values. A `mask: true` guardrail without that parent-side write-back still ships raw PII downstream.
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, address, passport, IP address, and more) plus country-specific identifiers across the US, UK, EU, India, Australia, Korea, Singapore, and others. Map the requirement to the closest enum value 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`, each with finer sub-categories (for example `hate_threatening`, `violence_graphic`, `self_harm_intent`). Requirements are usually described in everyday vocabulary rather than enum values, so map liberally:
- "explicit", "obscene", "vulgar", "NSFW" -> `sexual` and/or `harassment`
- "abusive", "insulting", "bullying", "toxic" -> `harassment`
- "hateful", "discriminatory", "racist", "sexist" -> `hate`
- "threatening", "intimidating" -> `harassment_threatening` or `violence`
- "suicide", "self-injury" -> `self_harm`
- "drugs", "weapons", "illegal activity" -> `illicit`
Do not invent category strings; the enum is fixed. When a requirement spans multiple categories, list all of them. Switch to `ai_agent` only when the policy is genuinely domain-specific (for example flagging content that mentions a competitor by name) -- that is a business rule, not a content-safety category.
### AI Agent: natural-language rules
Pick `ai_agent` only when the check needs judgment that does not fit `pii` or `moderation`: domain-specific compliance (HIPAA, SOX, GDPR), business-policy validation (price bounds, approval thresholds, discount rules), data-quality assertions, or any "evaluate against these custom rules" framing with no `pii.entities` or `moderation.categories` analogue.
The output format is **fixed** to a specific JSON shape and is not configurable. Every `ai_agent` guardrail returns:
```json
{
"flagged": true,
"reasoning": "Short explanation of why."
}
```
The fixed shape is what makes the verdict consumable by the parent's routers and filters without extra parsing. Do not describe an output schema in the instructions -- the engine constrains the output itself.
The instructions are the heart of an `ai_agent` guardrail. Good instructions:
- **State the rule clearly.** For example, "flag orders where discount > 30% AND customer account age < 90 days." Do not bury the rule in prose.
- **Define both outcomes.** Say what `flagged: true` and `flagged: false` each mean, including what belongs in `reasoning` for each.
- **Show, don't just tell.** A handful of input-to-output examples -- a clear pass, a clear fail, a borderline case -- do more than a paragraph of description.
- **Handle malformed input.** For example, "if the `discount` field is missing, return `flagged: true` with reasoning 'discount field missing -- cannot evaluate.'"
Some AI-agent capabilities deliberately do not apply to guardrails: no tools (no web search, MCP, Celigo Tools, or image generation) and no image or blob output -- the output is always the fixed `{flagged, reasoning}` JSON. Wanting any of those is a sign the design is really an AI agent step followed by a guardrail, not one `ai_agent` guardrail doing both.
## Confidence Threshold
Every guardrail has a `confidenceThreshold` (0.0 to 1.0, default 0.7), the single most-tuned knob across all three types. Detections at or above the threshold are flagged; below it, they are ignored.
- **Lower threshold** (for example 0.5) -- catches more potential issues but raises the false-positive rate. Use when missing a real issue is more expensive than reviewing a false flag (compliance or safety where human review is cheap).
- **Higher threshold** (for example 0.9) -- catches fewer issues, only high-confidence ones. Use when false positives are expensive, so auto-blocking does not trip on borderline cases.
- **Default 0.7** -- the sensible middle. Most production guardrails start here and tune from data.
For `pii` and `moderation`, the threshold is interpreted by the local classifier directly. For `ai_agent`, the model is instructed to include a confidence in its verdict and the same threshold applies.
## Input Modes -- What the Guardrail Evaluates
What a guardrail evaluates is shaped by which input field the mapping populates. There are four modes:
- **`record`** -- the in-flight record as stringified JSON. Use when the check spans the structured fields together (most `pii` cases scanning multiple fields, most business-rule `ai_agent` checks).
- **`text`** -- a single string, such as a ticket body, a chat message, or a generated paragraph. Use when the check is over one body of text (most `moderation` cases, and content screening before or after an AI agent).
- **`blob`** -- file content (PDFs, images) for the classifier or model to evaluate. Useful for `pii` or `moderation` over uploaded documents. Unsupported file types fail the record.
- **`conversationHistoryId`** -- a stable identifier so an `ai_agent` guardrail can reason against prior conversation history when the policy calls for it.
Modes can mix in a single record. **Mixed mode** (`record` + `text` + `blob` together) is common when the check needs structured data plus explanatory text plus reference documents -- for example a contract-compliance guardrail evaluating an order with the contract attached. Populate multiple destinations in the mapping and the runtime stitches them together.
If no mapping is defined, the guardrail evaluates the un-mapped in-flight record as `record` by default -- fine for prototypes, less precise than mapping explicitly.
## Placement in the Parent Pipeline
Guardrails are steps in flows, API endpoints, and Tools. They run per-record, return a verdict, and the parent's downstream structure (router, filter, next-step wiring) decides what happens next. Recurring placement patterns:
- **Right after the source, before expensive processing.** Run source records through a guardrail before routing clean records onward and flagged records to a review queue -- catching bad content early avoids wasting AI agent spend on records that should not be processed.
- **Right before an AI agent step.** Protect the model from unsafe inputs before it sees them: PII scrubbing keeps customer data out of inference, moderation catches toxic prompts, and an `ai_agent` guardrail can catch prompt-injection signals.
- **Right before the destination, gating what gets written.** Run records through a PII guardrail before pushing to a third-party warehouse or partner system so nothing leaks across the trust boundary.
- **Right after an AI agent step, validating model output.** A moderation guardrail after a content-generating agent verifies the output meets safety standards before it ships.
### Running Two Guardrails in Series
When a requirement names more than one orthogonal check (for example "flag PII OR explicit content"), build two guardrails in series -- a `pii` guardrail followed by a `moderation` guardrail -- with a router that branches on either being flagged. Run cheap deterministic classifiers first (`pii` then `moderation`) and the expensive `ai_agent` last, each guardrail short-circuiting the chain by routing flagged records elsewhere. The chained pattern (`pii -> moderation -> custom policy`) is common for layered defense.
Prefer chained simple guardrails over one `ai_agent` doing everything: chaining is cheaper (zero LLM calls for the deterministic steps), more predictable, easier to debug (you know which check flagged the record), and easier to evolve. Reach for a single `ai_agent` guardrail only when the rules genuinely inter-relate -- "reject orders where discount AND customer-age trigger together" is one rule, not two.
A guardrail is one layer in a defense-in-depth approach, never the only defense for high-stakes compliance or safety -- even deterministic classifiers have false negatives. Combine guardrails with downstream filters, review queues, and platform controls such as encryption, access control, and audit logs.
<!-- TIER:3 -->
## Gotchas
1. **Guardrails are imports.** They use `adaptorType: "GuardrailImport"` and live at `/v1/imports`. The CLI `guardrails` command is a virtual view that filters by adaptor type, but the underlying API is the imports endpoint.
2. **PUT erases omitted fields.** Always GET first, modify, then PUT. The `set` command handles this.
3. **BYOK model restrictions.** Without a BYOK connection, `ai_agent` guardrails are limited to platform-supported models. Setting an unsupported model returns a validation error. Add a connection first if you need a non-standard model.
4. **At least one entity or category required.** PII guardrails need at least one entry in `pii.entities[]`; moderation guardrails need at least one in `moderation.categories[]`. Empty arrays fail validation.
5. **Platform-managed credentials cover most cases.** BYOK connections are rare for guardrails. Don't add a `_connectionId` unless the user specifically needs a custom API key.
6. **Masking is off by default.** PII guardrails default to `mask: false` (flag-only mode). Set `mask: true` explicitly if detected PII should be redacted in the output.
7. **`mask: true` does not rewrite the record in place.** It returns a redacted payload under a `masked` field; the parent must author a response mapping (and a `postResponseMap` hook for record-mode masking) to write those values back onto the record. Without that parent-side write-back, raw PII still ships downstream.
8. **The verdict only propagates if the parent maps it.** Nothing the guardrail returns (`flagged`, `masked`) reaches downstream steps unless the parent authors a response mapping that extracts it -- guardrails flag, the parent enforces.
9. **`ai_agent` output shape is fixed.** Every `ai_agent` guardrail returns `{ flagged, reasoning }`. Do not specify an output schema in the instructions, and do not expect tools or image/blob output on the guardrail side.
10. **A guardrail is one layer, not the whole defense.** Even deterministic `pii` and `moderation` classifiers produce false negatives. Pair guardrails with downstream filters, review queues, and platform controls for high-stakes compliance or safety.
11. **Guardrail vs filter.** A filter gates on record **structure** (`status == "draft"`) -- cheap and deterministic. A guardrail gates on record **content** (contains PII, violates policy). Don't imitate moderation with keyword filters, and don't use a guardrail rule for a field comparison -- put an input filter on the guardrail step instead, which is also the cheapest cost knob for an `ai_agent` guardrail.
## Common Errors
| Error | Cause | Fix |
|-------|-------|-----|
| 422 `guardrail.type required` | Missing `guardrail.type` field | Set `guardrail.type` to `"pii"`, `"moderation"`, or `"ai_agent"` |
| 422 `entities required` | PII guardrail with empty entities array | Add at least one entity to `guardrail.pii.entities[]` |
| 422 `categories required` | Moderation guardrail with empty categories | Add at least one category to `guardrail.moderation.categories[]` |
| 422 `model not supported` | AI agent using unsupported model without BYOK | Use a platform-supported model or add a BYOK connection |
| 422 `adaptorType invalid` | Wrong case on adaptor type | Use exact case: `GuardrailImport` |