configuring-guardrails

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

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

_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.

防护栏是应用于Celigo集成中流转数据的安全与合规检查机制。防护栏以导入项形式存储，

adaptorType

值为

"GuardrailImport"

，可通过

/v1/imports

API访问，同时在Celigo UI中有专门的页面。

防护栏主要处理三类需求：

数据验证——在记录到达下游系统前，根据规则进行检查（PII检测、内容审核或自定义基于AI的评估）
置信度调优——通过
```
confidenceThreshold
```
参数（取值0到1，默认0.7）控制检测敏感度。值越低，能捕获更多潜在问题，但会增加误报率
PII掩码——可选在响应的
```
masked
```
字段中返回记录的脱敏副本（设置
```
pii.mask: true
```
）。掩码功能不会自动生效——详见PII：掩码 vs 标记

除非使用BYOK凭证配置

ai_agent

类型的防护栏，否则无需指定

_connectionId

。平台托管的凭证可覆盖大多数使用场景。

防护栏可在流程、API和工具中跨场景使用。

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.

在设计防护栏前，必须理解最重要的运行时语义：防护栏仅生成判定结果，不会对记录执行操作。被标记的记录是被拦截、路由到审核队列、丢弃、重试还是附加判定结果后转发，由父组件（流程、API端点或工具）的路由、分支或过滤结构决定——而非防护栏本身。防护栏的职责仅限于输出结构化JSON判定结果，后续所有操作均由父组件负责。

这种职责划分是刻意设计的。它使得每个防护栏可在多个父组件中复用（同一个「客户PII扫描器」可在一个流程中标记待审核记录、在API端点中拦截写入操作、在第三个场景中作为工具输出的校验门限），同时让每个防护栏的契约更简洁、易于测试，且审计轨迹更清晰。类似「拦截所有含PII的记录」或「将标记工单路由到Slack频道」这类需求，实际上包含两个决策：防护栏的精准检查，以及父组件的路由逻辑。防护栏负责实现检查逻辑，路由逻辑则在父组件中设计。

防护栏返回的任何内容，只有当父组件配置了响应映射来提取时，才会传递到下游步骤。

Three Types of Guardrail

三类防护栏

PII Detection

PII检测

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[]

检测记录中的个人身份信息。可配置要扫描的实体类型（电子邮件地址、社保号、信用卡号、电话号码等），以及是否对检测到的值进行掩码处理。

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[]

检查内容是否属于有害类别（仇恨言论、暴力、骚扰、色情内容、自残、非法活动）。

guardrail.moderation.categories[]

中至少需指定一种类别。

AI Agent Evaluation

AI Agent评估

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.

使用AI模型（OpenAI）根据自定义指令评估数据。通过

guardrail.aiAgent

配置（与

AiAgentImport

的 schema 一致）。支持模型选择、温度参数、结构化输出和推理功能。若无BYOK连接，仅可使用平台支持的OpenAI模型。

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
Block harmful content (hate, violence)	`moderation`	`guardrail.moderation.categories[]`	guardrail.yml
Custom AI-based validation rules	`ai_agent`	`guardrail.aiAgent` (provider, model, instructions)	guardrail.yml + aiagent.yml

你需要...	使用 `guardrail.type`	配置项	查看Schema
检测/掩码PII（电子邮件、社保号、信用卡）	`pii`	`guardrail.pii.entities[]` , `guardrail.pii.mask`	guardrail.yml
拦截有害内容（仇恨、暴力）	`moderation`	`guardrail.moderation.categories[]`	guardrail.yml
自定义基于AI的验证规则	`ai_agent`	`guardrail.aiAgent` （提供商、模型、指令）	guardrail.yml + 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{}

_connectionId

required unless using BYOK for

ai_agent

每个防护栏都需要以下字段：

```
name
```
——易于识别的人类可读标签
```
adaptorType
```
——固定为
```
"GuardrailImport"
```

guardrail.type

——取值为

"pii"

、

"moderation"

或

"ai_agent"

类型专属配置——

guardrail.pii{}

、

guardrail.moderation{}

或

guardrail.aiAgent{}

除非为

ai_agent

类型配置BYOK，否则无需

_connectionId

。

Schema Index

Schema索引

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)

所有Schema均位于references/schemas/：

基础字段（所有导入项）： request.yml
响应格式： response.yml
防护栏配置： guardrail.yml——类型、confidenceThreshold、pii、moderation
AI Agent配置： aiagent.yml——提供商、模型、指令、工具、结构化输出（与AiAgentImport共享）

Related Skills

How to Build a Guardrail

如何构建防护栏

1. Determine the compliance requirement

1. 确定合规需求

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)?

你需要哪种检查？PII检测（扫描敏感数据）、内容审核（拦截有害内容）还是自定义AI评估（应用业务特定规则）？

2. Check for existing guardrails

2. 检查现有防护栏

Before building from scratch, see what already exists in the account:

bash

undefined

在从零开始构建前，先查看账户中已有的防护栏：

bash

undefined

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"

undefined

celigo account search "guardrail" celigo account search "pii" celigo account search "moderation"

undefined

3. Choose the guardrail type

3. 选择防护栏类型

Refer to the Type Decision Matrix. Each type has a distinct configuration shape.

参考类型决策矩阵。每种类型的配置结构不同。

4. Configure type-specific settings

4. 配置类型专属设置

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.

PII： 选择要检测的实体类型。从最常见的类型开始：
```
email_address
```
、
```
phone_number
```
、
```
credit_card_number
```
、
```
persons_name
```
、
```
us_social_security_number
```
。如果下游步骤需要查看脱敏数据，启用
```
mask: true
```
——同时要规划所需的响应映射回写逻辑（详见PII：掩码 vs 标记）。
内容审核： 选择类别。核心三类是
```
hate
```
、
```
violence
```
、
```
harassment
```
。根据需求添加其他类别。
AI Agent： 为模型编写清晰的指令。目前防护栏仅支持OpenAI模型。若无BYOK连接，平台支持的OpenAI模型包括：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

5. 设置置信度阈值

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.

默认值为0.7。如需更严格的合规要求，可提高到0.8-0.9。如需更广泛的检测（伴随更多误报），可降低到0.4-0.5。查看guardrail.yml中的

confidenceThreshold

字段说明。

6. Build the guardrail JSON

6. 构建防护栏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.

参考Schema索引。务必查看request.yml获取基础字段，guardrail.yml获取防护栏配置，若使用

ai_agent

类型还需查看aiagent.yml。

CLI Commands

CLI命令

bash

undefined

bash

undefined

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>

undefined

celigo guardrails enable-debug <id> [--duration <minutes>] celigo guardrails disable-debug <id>

undefined

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). 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

和

moderation

属于本地确定性分类器——相同输入始终产生相同输出，无需调用LLM，无令牌成本，无模型延迟。

ai_agent

则是每条记录都调用一次真实LLM，因此存在成本和结果差异。只要需求匹配，优先选择成本更低的类型；

ai_agent

是兜底方案，而非默认选择：

pii  >  moderation  >  ai_agent

三类类型互斥——单个防护栏不能同时作为PII检测和内容审核。当需要两种独立的检查时，应串联两个防护栏步骤，而非合并为一个（详见在父管道中的位置）。选择类型的依据是检测对象，而非需求的表述方式：即使需求用自然语言描述，只要是关于PII的，就应选择

pii

类型。

PII: mask vs flag

PII：掩码 vs 标记

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.

在实体列表之后，PII防护栏最常调整的参数是

mask

：

mask: false
（默认）——检测结果会在判定中标记，数据原样传递，由下游路由决定后续操作。
mask: true
——检测结果会被标记，同时在防护栏响应的**
```
masked
```
字段中返回脱敏后的负载。这不是**自动的原地替换——防护栏不会改写流转中的记录。若要让下游系统接收脱敏后的值，父组件必须在防护栏步骤中配置响应映射，将
```
masked
```
字段提取回记录中；对于记录模式的掩码，还需配置
```
postResponseMap
```
钩子，用脱敏值覆盖原始PII字段。若未配置父组件侧的回写逻辑，即使设置了
```
mask: true
```
，原始PII仍会被传递到下游。

对于需要审核人员查看真实数据的场景，默认选择仅标记模式。对于跨信任边界的场景（第三方分析、AI供应商、合作伙伴集成、公开报告），默认选择

mask: true

——这类场景中，目标系统不应看到原始值，即使记录通过了检测。若不确定且目标系统是外部系统，优先选择掩码。

pii.entities[]

枚举值范围广泛且由平台固定：包含通用实体类型（电子邮件、电话、信用卡、社保号、姓名、地址、护照、IP地址等），以及美国、英国、欧盟、印度、澳大利亚、韩国、新加坡等国家/地区的专属标识符。当需求中的实体与枚举值不完全匹配时，优先映射到最接近的枚举值，而非切换到

ai_agent

类型。

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.

moderation.categories[]

枚举值由平台固定。顶级类别包括

sexual

、

hate

、

harassment

、

self_harm

、

violence

和

illicit

，每个类别下还有更细分的子类别（例如

hate_threatening

、

violence_graphic

、

self_harm_intent

）。需求通常用日常词汇描述，而非枚举值，因此需要灵活映射：

"露骨"、"淫秽"、"粗俗"、"NSFW" ->
```
sexual
```
和/或
```
harassment
```
"辱骂"、"侮辱"、"霸凌"、"有毒内容" ->
```
harassment
```
"仇恨"、"歧视"、"种族主义"、"性别歧视" ->
```
hate
```
"威胁"、"恐吓" ->
```
harassment_threatening
```
或
```
violence
```
"自杀"、"自伤" ->
```
self_harm
```
"毒品"、"武器"、"非法活动" ->
```
illicit
```

不要自定义类别字符串——枚举值是固定的。当需求涉及多个类别时，列出所有相关类别。只有当策略真正属于特定领域时（例如标记提及竞争对手名称的内容），才切换到

ai_agent

类型——这类需求属于业务规则，而非内容安全类别。

AI Agent: natural-language rules

AI Agent：自然语言规则

Pick

ai_agent

only when the check needs judgment that does not fit

pii

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

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.

仅当检查需要的判断逻辑不适合

pii

或

moderation

类型时，才选择

ai_agent

：特定领域的合规性（HIPAA、SOX、GDPR）、业务策略验证（价格范围、审批阈值、折扣规则）、数据质量断言，或任何无法用

pii.entities

或

moderation.categories

匹配的「根据自定义规则评估」场景。

输出格式是固定的特定JSON结构，不可配置。每个

ai_agent

防护栏都会返回：

json

{
  "flagged": true,
  "reasoning": "简短的原因说明。"
}

固定的结构使得判定结果无需额外解析即可被父组件的路由器和过滤器使用。不要在指令中描述输出schema——引擎会自动约束输出格式。

指令是

ai_agent

防护栏的核心。优质的指令应：

清晰陈述规则。例如："标记折扣>30%且客户账户时长<90天的订单。"不要将规则隐藏在冗长的文本中。
定义两种结果。说明
```
flagged: true
```
和
```
flagged: false
```
各自的含义，以及每种情况下
```
reasoning
```
字段应包含的内容。
示例演示，而非仅文字描述。少量输入到输出的示例——明确通过、明确失败、边界情况——比一段描述更有效。
处理格式错误的输入。例如："如果
```
discount
```
字段缺失，返回
```
flagged: true
```
，并在reasoning中说明'discount字段缺失——无法评估。'"

部分AI Agent功能不适用于防护栏：不支持工具（无网页搜索、MCP、Celigo Tools或图像生成），不支持图像或blob输出——输出始终是固定的

{flagged, reasoning}

JSON。如果需要这些功能，说明设计应该是AI Agent步骤后跟随防护栏，而非单个

ai_agent

防护栏同时完成两项任务。

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.

每个防护栏都有

confidenceThreshold

参数（取值0.0到1.0，默认0.7），这是所有三类防护栏中最常调整的参数。置信度达到或超过阈值的检测结果会被标记；低于阈值的则会被忽略。

较低阈值（例如0.5）——能捕获更多潜在问题，但会提高误报率。适用于遗漏真实问题的成本高于审核误报的场景（合规或安全场景，且人工审核成本较低）。
较高阈值（例如0.9）——捕获的问题更少，仅标记高置信度的结果。适用于误报成本较高的场景，避免自动拦截边界情况。
默认值0.7——合理的中间值。大多数生产环境的防护栏从该值开始，再根据实际数据调整。

对于

pii

和

moderation

类型，阈值由本地分类器直接解析。对于

ai_agent

类型，模型会被要求在判定结果中包含置信度，同样适用该阈值。

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.

防护栏评估的对象由映射配置的输入字段决定。共有四种模式：

record
——流转中的记录，以JSON字符串形式传入。适用于检查需要结合多个结构化字段的场景（大多数PII检测场景、大多数基于业务规则的AI Agent检查）。
text
——单个字符串，例如工单内容、聊天消息或生成的段落。适用于检查针对单一文本主体的场景（大多数内容审核场景，以及AI Agent前后的内容筛查）。
blob
——文件内容（PDF、图像），供分类器或模型评估。适用于对上传文档进行PII检测或内容审核的场景。不支持的文件类型会导致记录处理失败。
conversationHistoryId
——稳定的标识符，使得AI Agent防护栏可根据历史对话记录进行推理，适用于策略要求结合历史上下文的场景。

单个记录可混合多种模式。混合模式（同时使用

record

text

blob

）很常见，例如合同合规防护栏需要评估订单数据加说明文本加附件合同的场景。在映射中配置多个目标字段，运行时会自动将它们组合在一起。

如果未定义映射，防护栏默认将未映射的流转记录作为

record

进行评估——适合原型开发，但不如显式映射精准。

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.

防护栏是流程、API端点和工具中的步骤。它们逐条记录运行，返回判定结果，父组件的下游结构（路由器、过滤器、后续步骤连接）决定后续操作。常见的放置模式：

紧跟数据源，在昂贵处理之前。在将干净记录路由到下游、标记记录路由到审核队列之前，先让源记录通过防护栏——尽早捕获不良内容，避免浪费AI Agent资源处理不应被处理的记录。
紧跟AI Agent步骤之前。在模型看到输入前保护其安全：PII脱敏可防止客户数据进入推理过程，内容审核可捕获有毒提示，AI Agent防护栏可捕获提示注入信号。
紧跟目标系统之前，作为写入校验门限。在将记录推送到第三方数据仓库或合作伙伴系统前，先通过PII防护栏检查，避免敏感数据跨信任边界泄露。
紧跟AI Agent步骤之后，验证模型输出。在内容生成Agent之后添加内容审核防护栏，确保输出符合安全标准后再对外发送。

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.

当需求涉及多种独立检查时（例如「标记含PII或露骨内容的记录」），应串联两个防护栏——先运行

pii

防护栏，再运行

moderation

防护栏——并配置路由器根据任一防护栏的标记结果进行分支。优先运行成本低的确定性分类器（先

pii

再

moderation

），最后运行成本高的

ai_agent

，每个防护栏都可通过路由标记记录到其他位置来中断链条。链式模式（

pii -> moderation -> 自定义策略

）是分层防御的常见方式。

优先选择串联简单防护栏，而非用单个AI Agent完成所有检查：链式模式成本更低（确定性步骤无需调用LLM）、结果更可预测、更易于调试（可明确知道是哪个检查标记了记录）、更易于扩展。仅当规则真正相互关联时，才使用单个AI Agent防护栏——例如「拒绝折扣和客户时长同时触发的订单」是单一规则，而非两个独立规则。

防护栏是深度防御方法中的一层，绝不是高风险合规或安全场景的唯一防御手段——即使是确定性分类器也存在漏报。应将防护栏与下游过滤器、审核队列和平台控制（如加密、访问控制、审计日志）结合使用。

Gotchas

注意事项

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.
PUT erases omitted fields. Always GET first, modify, then PUT. The
```
set
```
command handles this.
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.
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.
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.
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.
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.
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.
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.
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.
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.

防护栏属于导入项。它们使用
```
adaptorType: "GuardrailImport"
```
，存储在
```
/v1/imports
```
路径下。CLI的
```
guardrails
```
命令是按适配器类型过滤的虚拟视图，但底层API是导入项端点。
PUT请求会删除未指定的字段。务必先执行GET请求，修改后再执行PUT请求。
```
set
```
命令会自动处理此问题。
BYOK模型限制。若无BYOK连接，
```
ai_agent
```
类型防护栏仅可使用平台支持的模型。设置不支持的模型会返回验证错误。如需使用非标准模型，需先添加BYOK连接。
至少需要一个实体或类别。PII防护栏的
```
pii.entities[]
```
中至少需有一个条目；内容审核防护栏的
```
moderation.categories[]
```
中至少需有一个条目。空数组会导致验证失败。
平台托管凭证覆盖大多数场景。防护栏很少需要BYOK连接。除非用户明确需要自定义API密钥，否则不要添加
```
_connectionId
```
。
掩码默认关闭。PII防护栏默认设置为
```
mask: false
```
（仅标记模式）。若需对检测到的PII进行脱敏输出，需显式设置
```
mask: true
```
。
mask: true
不会原地改写记录。它会在
```
masked
```
字段中返回脱敏负载；父组件必须配置响应映射（以及记录模式掩码所需的
```
postResponseMap
```
钩子）才能将这些值写回记录。若无父组件侧的回写逻辑，原始PII仍会被传递到下游。
判定结果仅在父组件映射后才会传播。防护栏返回的任何内容（
```
flagged
```
、
```
masked
```
），只有当父组件配置了响应映射来提取时，才会传递到下游步骤——防护栏仅标记，父组件负责执行。
ai_agent
输出结构固定。每个
```
ai_agent
```
防护栏都会返回
```
{ flagged, reasoning }
```
。不要在指令中指定输出schema，也不要期望防护栏返回工具或图像/blob输出。
防护栏只是一层防御，而非全部。即使是确定性的
```
pii
```
和
```
moderation
```
分类器也会存在漏报。对于高风险合规或安全场景，需将防护栏与下游过滤器、审核队列和平台控制结合使用。
防护栏 vs 过滤器。过滤器基于记录结构进行校验（
```
status == "draft"
```
）——成本低且确定性强。防护栏基于记录内容进行校验（包含PII、违反策略）。不要用关键词过滤器模拟内容审核，也不要用防护栏规则进行字段比较——应在防护栏步骤上配置输入过滤器，这也是AI Agent防护栏最有效的成本控制手段。

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`

错误	原因	修复方法
422 `guardrail.type required`	缺失 `guardrail.type` 字段	将 `guardrail.type` 设置为 `"pii"` 、 `"moderation"` 或 `"ai_agent"`
422 `entities required`	PII防护栏的entities数组为空	向 `guardrail.pii.entities[]` 中添加至少一个实体
422 `categories required`	内容审核防护栏的categories数组为空	向 `guardrail.moderation.categories[]` 中添加至少一个类别
422 `model not supported`	AI Agent使用了不支持的模型且未配置BYOK	使用平台支持的模型，或添加BYOK连接
422 `adaptorType invalid`	适配器类型大小写错误	使用精确的大小写： `GuardrailImport`

configuring-guardrails

Original

Translation

Configuring Guardrails

配置防护栏

Guardrails Flag, They Don't Enforce

防护栏仅标记，不强制执行

Three Types of Guardrail

三类防护栏

PII Detection

PII检测

Content Moderation

内容审核

AI Agent Evaluation

AI Agent评估

Quick Reference

快速参考

Type Decision Matrix

类型决策矩阵

Minimum Required Fields

必填字段

Schema Index

Schema索引

Related Skills

相关技能

How to Build a Guardrail

如何构建防护栏

1. Determine the compliance requirement

1. 确定合规需求

2. Check for existing guardrails

2. 检查现有防护栏

List all guardrails

列出所有防护栏

Search the account for guardrail-related resources

在账户中搜索防护栏相关资源

3. Choose the guardrail type

3. 选择防护栏类型

4. Configure type-specific settings

4. 配置类型专属设置

5. Set the confidence threshold

5. 设置置信度阈值

6. Build the guardrail JSON

6. 构建防护栏JSON

CLI Commands

CLI命令

CRUD

增删改查操作

Invoke (test a guardrail against sample data)

调用（针对样本数据测试防护栏）

Clone and connection management

克隆与连接管理

Discovery

发现

Debug

调试

Configuring Each Type in Depth

各类型深度配置

PII: mask vs flag

PII：掩码 vs 标记

Moderation: categories

内容审核：类别

AI Agent: natural-language rules

AI Agent：自然语言规则

Confidence Threshold

置信度阈值

Input Modes -- What the Guardrail Evaluates

输入模式——防护栏评估的对象

Placement in the Parent Pipeline

在父管道中的位置

Running Two Guardrails in Series

串联两个防护栏

Gotchas

注意事项

Common Errors

常见错误