configuring-ai-agents

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

Configuring AI Agents

配置AI Agent

An AI agent is an LLM-powered import step that processes records through an AI model instead of writing them to an external system. Records flow in, the model processes them according to instructions, and structured output flows back into the pipeline.

AI agents handle four concerns:

Prompt design -- the system instruction that defines the model's behavior, goals, and constraints (up to 50 KB). The prompt receives each record as context and must produce output that downstream steps can consume
Structured output --
```
json_schema
```
output format forces the model to return data conforming to a JSON Schema, enabling reliable field extraction for mapping.
```
text
```
returns free-form responses.
```
blob
```
returns binary data (image generation)
Tool use -- the model can call web search, MCP server tools, Celigo Tool resources, or image generation during processing. Tools extend the model's capabilities beyond its training data
Response mapping -- extract fields from the model's response back into the record for downstream steps. Configured on the flow's
```
pageProcessors[]
```
entry, but planned when building the agent. The response is available via
```
_json
```
. Response mapping uses Transformation 1.0 syntax (extract/generate pairs)

AI agents do not require a

_connectionId

unless using BYOK (bring your own key). Without one, platform-managed credentials are used.

Used across flows, APIs, and tools.

AI Agent是一种由LLM驱动的导入步骤，它通过AI模型处理记录，而非将记录写入外部系统。记录流入后，模型会根据指令处理它们，结构化输出会回流到流水线中。

AI Agent处理四类核心事项：

提示词设计——定义模型行为、目标和约束的系统指令（最大50 KB）。提示词会将每条记录作为上下文接收，且必须生成下游步骤可消费的输出
结构化输出——
```
json_schema
```
输出格式强制模型返回符合JSON Schema的数据，为映射提供可靠的字段提取能力。
```
text
```
返回自由格式响应。
```
blob
```
返回二进制数据（如图像生成）
工具调用——模型在处理过程中可调用网页搜索、MCP服务器工具、Celigo Tool资源或图像生成工具。工具可扩展模型超出其训练数据的能力
响应映射——从模型响应中提取字段并回流到记录中供下游步骤使用。在流程的
```
pageProcessors[]
```
条目上配置，但需在构建Agent时规划。响应可通过
```
_json
```
获取。响应映射使用Transformation 1.0语法（提取/生成对）

AI Agent无需

_connectionId

，除非使用BYOK（自带密钥）。若未配置，则使用平台托管的凭据。

可在流程、API和工具中通用。

Two Types of AI Import

两种AI导入类型

AI Agent Imports

AI Agent导入项

Invoke an LLM for classification, extraction, summarization, translation, or generation. Two providers:

OpenAI (
```
provider: "openai"
```
) -- GPT models via the OpenAI Responses API. Supports reasoning effort control, structured JSON output, web search, MCP tools, Celigo Tools, and image generation.
Gemini (
```
provider: "gemini"
```
) -- Google Gemini models via LiteLLM proxy. Supports thinking config, Google Search grounding, URL context, file search, MCP tools, and Celigo Tools.

调用LLM执行分类、提取、摘要、翻译或生成任务。支持两种供应商：

OpenAI（
```
provider: "openai"
```
）——通过OpenAI Responses API调用GPT模型。支持推理力度控制、结构化JSON输出、网页搜索、MCP工具、Celigo Tools和图像生成。
Gemini（
```
provider: "gemini"
```
）——通过LiteLLM代理调用Google Gemini模型。支持思考配置、Google Search grounding、URL上下文、文件搜索、MCP工具和Celigo Tools。

Guardrail Imports

防护栏导入项

Safety and compliance checks applied to data flowing through integrations. Three sub-types:

ai_agent -- uses an AI model to evaluate data against custom instructions (reuses the same
```
aiAgent
```
config as AI Agent imports)
pii -- detects and optionally masks personally identifiable information (email, SSN, credit card, etc.)
moderation -- checks content against moderation categories (hate speech, violence, harassment, etc.)

Guardrails do not require a

_connectionId

unless using BYOK for the

ai_agent

sub-type.

AI agent vs guardrail: pick by what the LLM produces. A guardrail renders a fixed verdict (

flagged: true|false

plus reasoning) that the parent's routing branches on -- reach for it when the user says "verify / check / validate / flag / screen". An AI agent step does work whose output flows onward as data -- reach for it when the user says "classify / extract / generate / summarize / decide". Guardrails flag; they never block on their own -- the parent flow/API/tool decides what happens to flagged records (see configuring-guardrails).

应用于集成流程中数据的安全与合规检查。包含三个子类型：

ai_agent——使用AI模型根据自定义指令评估数据（复用与AI Agent导入项相同的
```
aiAgent
```
配置）
pii——检测并可选屏蔽个人身份信息（邮箱、社保号、信用卡等）
moderation——检查内容是否符合审核类别（仇恨言论、暴力、骚扰等）

防护栏无需

_connectionId

，除非

ai_agent

子类型使用BYOK。

AI Agent vs 防护栏：根据LLM生成的内容选择。防护栏会生成固定的判定结果（

flagged: true|false

加推理说明），供父级路由分支使用——当用户需求为“验证/检查/确认/标记/筛查”时使用。AI Agent步骤会执行实际处理，其输出作为数据流转到下游——当用户需求为“分类/提取/生成/摘要/决策”时使用。防护栏仅做标记，本身不会拦截数据——父级流程/API/工具决定如何处理标记的记录（详见configuring-guardrails）。

Quick Reference

快速参考

Adaptor Decision Matrix

适配器决策矩阵

You need...	Use adaptorType	Config block	Read schema
LLM classification, extraction, generation	`AiAgentImport`	`aiAgent{}`	aiagent.yml
PII detection or masking	`GuardrailImport`	`guardrail{}`	guardrail.yml
Content moderation	`GuardrailImport`	`guardrail{}`	guardrail.yml
AI-based custom validation	`GuardrailImport` with `guardrail.type: "ai_agent"`	`guardrail.aiAgent{}`	guardrail.yml + aiagent.yml

adaptorType

is case-sensitive:

AiAgentImport

, not

aiagentimport

需求场景	使用adaptorType	配置块	参考Schema
LLM分类、提取、生成	`AiAgentImport`	`aiAgent{}`	aiagent.yml
PII检测或屏蔽	`GuardrailImport`	`guardrail{}`	guardrail.yml
内容审核	`GuardrailImport`	`guardrail{}`	guardrail.yml
基于AI的自定义验证	`GuardrailImport` 搭配 `guardrail.type: "ai_agent"`	`guardrail.aiAgent{}`	guardrail.yml + aiagent.yml

adaptorType

区分大小写：需使用

AiAgentImport

，而非

aiagentimport

。

Provider Decision Matrix

供应商决策矩阵

Provider Config path Instructions field Models Tool types

OpenAI

Provider	Config path	Instructions field	Models	Tool types
OpenAI	`aiAgent.openai{}`	`openai.instructions`	`gpt-4.1-mini` , `gpt-5-mini` , `gpt-5` , `gpt-4.1` , `gpt-5-pro` , `gpt-4.1-nano`	`web_search` , `mcp` , `tool` , `image_generation`
Gemini	`aiAgent.litellm{}`	`litellm._overrides.gemini.systemInstruction`	`gemini/gemini-2.5-pro` , `gemini/gemini-2.5-flash`	`googleSearch` , `urlContext` , `fileSearch` , `mcp` , `tool`

aiAgent.openai{}

openai.instructions

gpt-4.1-mini

gpt-5-mini

gpt-5

gpt-4.1

gpt-5-pro

gpt-4.1-nano

web_search

mcp

tool

image_generation

Gemini

aiAgent.litellm{}

litellm._overrides.gemini.systemInstruction

gemini/gemini-2.5-pro

gemini/gemini-2.5-flash

googleSearch

urlContext

fileSearch

mcp

tool

供应商配置路径指令字段模型工具类型

OpenAI

供应商	配置路径	指令字段	模型	工具类型
OpenAI	`aiAgent.openai{}`	`openai.instructions`	`gpt-4.1-mini` , `gpt-5-mini` , `gpt-5` , `gpt-4.1` , `gpt-5-pro` , `gpt-4.1-nano`	`web_search` , `mcp` , `tool` , `image_generation`
Gemini	`aiAgent.litellm{}`	`litellm._overrides.gemini.systemInstruction`	`gemini/gemini-2.5-pro` , `gemini/gemini-2.5-flash`	`googleSearch` , `urlContext` , `fileSearch` , `mcp` , `tool`

aiAgent.openai{}

openai.instructions

gpt-4.1-mini

gpt-5-mini

gpt-5

gpt-4.1

gpt-5-pro

gpt-4.1-nano

web_search

mcp

tool

image_generation

Gemini

aiAgent.litellm{}

litellm._overrides.gemini.systemInstruction

gemini/gemini-2.5-pro

gemini/gemini-2.5-flash

googleSearch

urlContext

fileSearch

mcp

tool

Minimum Required Fields

必填字段

AiAgentImport:

name

adaptorType: "AiAgentImport"

aiAgent.provider

, and provider config (

aiAgent.openai{}

aiAgent.litellm{}

). Instructions and model are required within the provider block.

GuardrailImport:

name

adaptorType: "GuardrailImport"

guardrail.type

, and the sub-type config (

guardrail.pii{}

guardrail.moderation{}

, or

guardrail.aiAgent{}

AiAgentImport：

name

、

adaptorType: "AiAgentImport"

、

aiAgent.provider

，以及供应商配置（

aiAgent.openai{}

或

aiAgent.litellm{}

）。供应商块内必须包含指令和模型。

GuardrailImport：

name

、

adaptorType: "GuardrailImport"

、

guardrail.type

，以及子类型配置（

guardrail.pii{}

guardrail.moderation{}

或

guardrail.aiAgent{}

）。

Schema Index

Schema索引

All schemas are in references/schemas/:

Base fields (all imports): request.yml
Response shape: response.yml
AI agent config: aiagent.yml -- provider, model, instructions, reasoning, temperature, output format, tools
Guardrail config: guardrail.yml -- PII entities, moderation categories, AI-based validation, confidence threshold

所有Schema均位于references/schemas/：

基础字段（所有导入项）：request.yml
响应结构：response.yml
AI Agent配置：aiagent.yml——供应商、模型、指令、推理、温度、输出格式、工具
防护栏配置：guardrail.yml——PII实体、审核类别、基于AI的验证、置信度阈值

Input Fields

输入字段

An AI agent step receives an in-flight record and maps parts of it into one of four input fields. The mapping destination dropdown shows exactly these four -- no more:

Field	Type	Purpose
`text`	string	Free text for the model to reason over. The most common input
`record`	object or array	The full structured record (or part of it) as JSON. Use when the model needs to see multiple fields together
`files`	array of `{ name, blobKey }`	File references. Text files are sent inline; images and PDFs are converted to a pre-signed URL the model fetches; other file types error
`conversationHistoryId`	string	Stable per-conversation identifier that retains and replays history across runs (see Conversation History)

If no input mapping is defined, the agent receives the un-mapped in-flight record as

record

by default.

AI Agent步骤会接收流转中的记录，并将其部分内容映射到四个输入字段之一。映射目标下拉列表仅显示这四个字段：

字段	类型	用途
`text`	字符串	供模型推理的自由文本。最常用的输入类型
`record`	对象或数组	完整的结构化记录（或其部分），以JSON格式传递。当模型需要查看多个字段的组合时使用
`files`	`{ name, blobKey }` 数组	文件引用。文本文件会直接内联发送；图片和PDF会转换为预签名URL供模型获取；其他文件类型会报错
`conversationHistoryId`	字符串	稳定的会话标识符，可在多次运行中保留和重放历史记录（详见会话历史）

若未定义输入映射，Agent默认会将未映射的流转记录作为

record

接收。

Output Formats

输出格式

The output format determines both what the model returns and which response variable carries it into response mapping:

Format	Response variable	Use for
`text`	`_text`	Free-form text -- summaries, generated content, classifications parsed downstream
`json_schema`	`_json`	Structured JSON conforming to a schema. Use when downstream steps need consistent fields. With `strict: true` , non-conforming outputs fail rather than pass through
`blob`	`blobKey`	Binary content stored in Celigo blob storage that downstream steps fetch or forward. Used for image generation

The response-mapping dropdown only shows the response field the chosen output format can produce.

输出格式决定了模型返回的内容类型，以及哪个响应变量会将其带入响应映射：

格式	响应变量	适用场景
`text`	`_text`	自由格式文本——摘要、生成内容、需下游解析的分类结果
`json_schema`	`_json`	符合Schema的结构化JSON。当下游步骤需要从响应中映射特定字段时使用。若设置 `strict: true` ，不符合Schema的输出会直接失败，而非流转到下游
`blob`	`blobKey`	存储在Celigo blob存储中的二进制内容，可供下游步骤获取或转发。用于图像生成场景

响应映射下拉列表仅显示所选输出格式可生成的响应字段。

Related Skills

How to Build an AI Agent

如何构建AI Agent

1. Determine the task

1. 确定任务

What should the AI model do with each record? Common patterns: classification (sentiment, routing), extraction (invoice parsing, address normalization), validation (business rules), generation (translations, summaries), enrichment (web search augmentation). The task determines the provider, model, output format, and whether tools are needed.

AI模型需要对每条记录执行什么操作？常见场景：分类（情感分析、路由）、提取（发票解析、地址标准化）、验证（业务规则）、生成（翻译、摘要）、补充（网页搜索增强）。任务类型决定了供应商、模型、输出格式以及是否需要工具。

2. Check for existing patterns

2. 检查现有模式

bash

undefined

bash

undefined

Search for existing AI agents in the account

搜索账户中已有的AI Agent

celigo ai-agents list

Search across the entire account

搜索整个账户

celigo account search "ai agent" celigo account search "<task keyword>"

undefined

celigo account search "ai agent" celigo account search "<任务关键词>"

undefined

3. Choose the provider and model

3. 选择供应商和模型

Use OpenAI for most tasks -- it has broader tool support and reasoning controls. Use Gemini when you need Google Search grounding, URL context retrieval, or file search.

Within each provider, choose the model based on the task complexity:

Simple tasks (classification, routing): use smaller models (
```
gpt-4.1-mini
```
,
```
gpt-4.1-nano
```
,
```
gpt-5-mini
```
,
```
gpt-5-nano
```
)
Complex tasks (multi-step reasoning, extraction): use larger models (
```
gpt-4.1
```
,
```
gpt-5
```
,
```
gpt-5-pro
```
)
Cost-sensitive: smaller models process faster and cost less

大多数任务优先选择OpenAI——它支持更广泛的工具和推理控制。当需要Google Search grounding、URL上下文检索或文件搜索时，选择Gemini。

在每个供应商下，根据任务复杂度选择模型：

简单任务（分类、路由）：使用小型模型（
```
gpt-4.1-mini
```
,
```
gpt-4.1-nano
```
,
```
gpt-5-mini
```
,
```
gpt-5-nano
```
）
复杂任务（多步推理、提取）：使用大型模型（
```
gpt-4.1
```
,
```
gpt-5
```
,
```
gpt-5-pro
```
）
成本敏感场景：小型模型处理速度更快、成本更低

4. Write the instructions

4. 编写指令

The system instruction is the most important configuration. Be specific about the task, expected input shape, and desired output. Include examples for complex tasks. Set constraints for edge cases (empty fields, invalid data). Keep instructions focused on a single responsibility per agent.

系统指令是最重要的配置项。需明确任务、预期输入格式和期望输出。复杂任务需包含示例。为边缘情况（空字段、无效数据）设置约束。每个Agent的指令应聚焦单一职责。

5. Configure the output format

5. 配置输出格式

Three options:

json_schema
-- forces structured JSON output conforming to a schema. Use this whenever downstream steps need to map specific fields from the response. Define the schema in
```
output.format.jsonSchema
```
(OpenAI) or
```
responseFormat.jsonSchema
```
(Gemini)
text
-- free-form text response. Use for summarization, translation, or when the entire response is one field
blob
-- binary output (image generation use cases)

For

json_schema

, set

strict: true

if you need guaranteed schema conformance (slightly higher latency).

有三种选项：

json_schema
——强制返回符合Schema的结构化JSON。当下游步骤需要从响应中映射特定字段时使用。在
```
output.format.jsonSchema
```
（OpenAI）或
```
responseFormat.jsonSchema
```
（Gemini）中定义Schema
text
——自由格式文本响应。用于摘要、翻译或整个响应为单一字段的场景
blob
——二进制输出（图像生成场景）

对于

json_schema

，若需要保证Schema一致性，设置

strict: true

（会略微增加延迟）。

6. Tune parameters

6. 调优参数

reasoning.effort
(OpenAI) or thinkingConfig.thinkingLevel
(Gemini) -- controls depth of reasoning. Use
```
"medium"
```
for most tasks;
```
"low"
```
for simple classification;
```
"high"
```
for complex analysis
temperature
--
```
0.2
```
for deterministic output (data extraction, classification);
```
1.0+
```
for creative generation
maxOutputTokens
/ maxCompletionTokens
-- set based on expected response size.
```
1000
```
for short classifications;
```
5000-20000
```
for detailed extractions;
```
100000+
```
for long-form generation

reasoning.effort
（OpenAI）或**
```
thinkingConfig.thinkingLevel
```
**（Gemini）——控制推理深度。大多数任务使用
```
"medium"
```
；简单分类使用
```
"low"
```
；复杂分析使用
```
"high"
```
temperature
——
```
0.2
```
用于确定性输出（数据提取、分类）；
```
1.0+
```
用于创意生成
maxOutputTokens
/ maxCompletionTokens
——根据预期响应大小设置。短分类设置为
```
1000
```
；详细提取设置为
```
5000-20000
```
；长文本生成设置为
```
100000+
```

7. Add tools (if needed)

7. 添加工具（如有需要）

Tools extend what the model can do during processing:

web_search
(OpenAI) / googleSearch
(Gemini) -- search the web for current information to enrich records
mcp
-- connect to an MCP server for external tool calls. Requires an MCP connection (
```
_mcpConnectionId
```
). Optionally restrict with
```
allowedTools
```
tool
-- invoke a Celigo Tool resource. Reference via
```
_toolId
```
. Supports per-agent
```
overrides
```
image_generation
(OpenAI) -- generate images from text descriptions
urlContext
(Gemini) -- fetch and process URL content
fileSearch
(Gemini) -- search uploaded files

工具可扩展模型在处理过程中的能力：

web_search
（OpenAI）/ googleSearch
（Gemini）——搜索网页获取最新信息以补充记录
mcp
——连接到MCP服务器调用外部工具。需要MCP连接（
```
_mcpConnectionId
```
）。可通过
```
allowedTools
```
限制可用工具
tool
——调用Celigo Tool资源。通过
```
_toolId
```
引用。支持每个Agent的
```
overrides
```
配置
image_generation
（OpenAI）——根据文本描述生成图像
urlContext
（Gemini）——获取并处理URL内容
fileSearch
（Gemini）——搜索上传的文件

8. Configure BYOK (optional)

8. 配置BYOK（可选）

By default, AI agents use platform-managed credentials. To use your own API key, create an HTTP connection with your provider's API key and set

_connectionId

on the import, or use

celigo ai-agents replace-connection <agentId> <connectionId>

默认情况下，AI Agent使用平台托管的凭据。若要使用自己的API密钥，创建包含供应商API密钥的HTTP连接，并在导入项上设置

_connectionId

，或使用命令

celigo ai-agents replace-connection <agentId> <connectionId>

。

9. Build the JSON

9. 构建JSON

Read the schema files from the Schema Index. Start with request.yml for base fields, then aiagent.yml for the provider configuration block.

参考Schema索引中的Schema文件。从request.yml的基础字段开始，然后添加aiagent.yml中的供应商配置块。

Celigo AI vs BYOK

Cutting across both providers is a second decision: run the agent on Celigo AI (platform-managed credentials) or BYOK (bring your own key).

Celigo AI -- no API key to manage. The trade is restriction: model choice is limited to Celigo's curated per-provider list (a subset of the GPT-5 and GPT-4.1 families on OpenAI; the Gemini 2.5 family on Gemini), and usage counts against the account's monthly AI token quota
BYOK -- the agent uses your own API key (configured on a connection; see step 8 above). Any model the provider supports is available -- new releases, fine-tuned models, models off Celigo's curated list -- and quota and rate limiting move to your provider account

Default to Celigo AI for prototyping, low-volume agents, and agents happy with the curated model list. Reach for BYOK when you need a model that isn't on the list, when volume would exceed the monthly token quota, or when you want costs to land on your existing AI vendor billing.

Switching between Celigo AI and BYOK -- or changing the model -- can drop configuration that no longer applies:

serviceTier

is BYOK-only,

reasoning.effort

applies only to reasoning-capable models, and image modalities apply only to image-capable Gemini models. It is not a one-knob change.

除了供应商选择，还需决定是使用Celigo AI（平台托管凭据）还是BYOK（自带密钥）运行Agent。

Celigo AI——无需管理API密钥。局限性：模型选择仅限于Celigo为每个供应商精选的列表（OpenAI的GPT-5和GPT-4.1系列子集；Gemini的Gemini 2.5系列），使用量会计入账户的月度AI令牌配额
BYOK——Agent使用您自己的API密钥（在连接中配置；详见步骤8）。支持供应商提供的任何模型——新版本、微调模型、Celigo精选列表外的模型——配额和速率限制由您的供应商账户管控

原型开发、低流量Agent以及满足于精选模型列表的Agent默认使用Celigo AI。当需要列表外的模型、使用量会超出月度令牌配额，或希望成本计入现有AI供应商账单时，选择BYOK。

在Celigo AI和BYOK之间切换——或更换模型——可能会导致不再适用的配置被清除：

serviceTier

仅适用于BYOK，

reasoning.effort

仅适用于支持推理的模型，图像模态仅适用于支持图像的Gemini模型。这并非一键切换操作。

Conversation History

会话历史

By default, AI agent steps are stateless -- each record is its own conversation and the agent has no memory of previous records. This keeps behavior reproducible and cost predictable.

To make an agent stateful, map a stable per-conversation identifier into its

conversationHistoryId

input field -- a Slack thread ID, session UUID, customer ID, or ticket number, whatever is unique per conversation. Celigo retains the conversation history for that identifier and replays it on subsequent calls, so the agent sees prior turns. Mapping

record.slack_thread_id

, for example, makes every reply in a Slack thread aware of the earlier messages.

The identifier is scoped per user and per agent: the same string used by two different agents is two separate conversations, and the same agent used by two different users is two separate conversations. The retained history is not accessible through public APIs or the UI -- it exists for the model to read, not for users to browse -- and idle conversations age out via a TTL that resets on each update.

默认情况下，AI Agent步骤是无状态的——每条记录都是独立的会话，Agent不会保留之前记录的记忆。这确保了行为可重现且成本可预测。

若要使Agent变为有状态，将稳定的会话标识符映射到其

conversationHistoryId

输入字段——例如Slack线程ID、会话UUID、客户ID或工单编号，任何会话唯一的标识即可。Celigo会保留该标识符对应的会话历史，并在后续调用中重放，因此Agent可以看到之前的对话回合。例如，映射

record.slack_thread_id

可使Slack线程中的每条回复都能感知到之前的消息。

标识符的作用域为每个用户和每个Agent：同一个字符串被两个不同Agent使用时，会被视为两个独立的会话；同一个Agent被两个不同用户使用时，也会被视为两个独立的会话。保留的历史记录无法通过公开API或UI访问——仅供模型读取，不供用户浏览——闲置会话会通过TTL机制过期，每次更新都会重置TTL。

Capability Check Before Building

构建前的能力检查

Before building an agent, walk through each action the requirement says the agent should perform and confirm each one maps to a capability the agent will actually have at runtime. The goal is to surface gaps early, not to refuse capabilities.

Capabilities come from three places:

Native to the chosen model -- OpenAI's
```
web_search
```
and
```
image_generation
```
; Gemini's
```
googleSearch
```
,
```
urlContext
```
,
```
fileSearch
```
, and image-modality output
Tools wired into the agent --
```
mcp
```
tools and Celigo Tools
Downstream steps in the parent -- rendering output, writing to a destination, notifying a recipient (same shape whether the parent is a flow, API endpoint, or Tool)

For each action, ask which of the three covers it; if none do, that is a gap to raise before building. A common example is "generate a PDF invoice": no provider ships PDF rendering as a native capability, so the right shape is the agent emitting structured invoice content (

json_schema

output) with a downstream step or Celigo Tool rendering the PDF. Equally, don't enable capabilities the requirement didn't ask for -- "classify support tickets" needs text classification (native), not

web_search

"just in case."

在构建Agent之前，逐一确认需求中Agent应执行的每个操作是否对应其运行时实际具备的能力。目的是提前发现缺口，而非拒绝需求。

能力来源于三个方面：

所选模型原生支持——OpenAI的
```
web_search
```
和
```
image_generation
```
；Gemini的
```
googleSearch
```
、
```
urlContext
```
、
```
fileSearch
```
和图像模态输出
接入Agent的工具——
```
mcp
```
工具和Celigo Tools
父级流程的下游步骤——渲染输出、写入目标、通知接收方（无论父级是流程、API端点还是Tool，结构都相同）

对于每个操作，确认由哪一方面提供支持；若均不支持，则需在构建前提出缺口。常见示例：“生成PDF发票”——没有供应商原生支持PDF渲染，正确的方案是Agent输出结构化发票内容（

json_schema

输出），然后由下游步骤或Celigo Tool渲染PDF。同样，不要启用需求未提及的能力——“分类支持工单”仅需要文本分类（原生能力），无需“以防万一”启用

web_search

。

How to Build a Guardrail

如何构建防护栏

1. Choose the guardrail type

1. 选择防护栏类型

pii
-- detect (and optionally mask) personally identifiable information. Configure which entity types to scan for in
```
guardrail.pii.entities
```
. Note:
```
mask: true
```
returns the redacted payload under a
```
masked
```
response field -- downstream steps only see it if you author a response-mapping write-back (see configuring-guardrails > PII: mask vs flag)
moderation
-- check content against harmful categories. Configure which categories in
```
guardrail.moderation.categories
```
ai_agent
-- custom AI-powered validation using the same LLM configuration as AI Agent imports

pii
——检测（并可选屏蔽）个人身份信息。在
```
guardrail.pii.entities
```
中配置需要扫描的实体类型。注意：
```
mask: true
```
会在
```
masked
```
响应字段下返回脱敏后的负载——下游步骤仅在您编写了响应映射回写时才能看到（详见configuring-guardrails > PII: mask vs flag）
moderation
——检查内容是否符合有害类别。在
```
guardrail.moderation.categories
```
中配置需要检查的类别
ai_agent
——使用与AI Agent导入项相同的LLM配置进行自定义AI驱动验证

2. Set the confidence threshold

2. 设置置信度阈值

guardrail.confidenceThreshold

(0 to 1, default 0.7) controls sensitivity. Lower values catch more potential issues but increase false positives.

guardrail.confidenceThreshold

（0到1，默认0.7）控制检测灵敏度。值越低，越容易检测到潜在问题，但误报率会增加。

3. Build the JSON

3. 构建JSON

Read guardrail.yml for all configuration options. For the

ai_agent

sub-type, also read aiagent.yml.

参考guardrail.yml获取所有配置选项。对于

ai_agent

子类型，还需参考aiagent.yml。

CLI Commands

CLI命令

bash

undefined

bash

undefined

CRUD -- AI Agents

celigo ai-agents list celigo ai-agents get <id> celigo ai-agents create < agent.json celigo ai-agents update <id> < agent.json celigo ai-agents set <id> key=value [key2=value2 ...] celigo ai-agents delete <id> [-y]

Invoke (test without creating a job)

调用（无需创建任务即可测试）

echo '[{"text":"classify this"}]' | celigo ai-agents invoke <id>

Clone and connection management

克隆和连接管理

celigo ai-agents clone <id> celigo ai-agents replace-connection <id> <newConnectionId>

Debug

调试

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

CRUD -- Guardrails

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 without creating a job)

调用（无需创建任务即可测试）

echo '[{"text":"check this content"}]' | celigo guardrails invoke <id>

Clone and connection management

克隆和连接管理

celigo guardrails clone <id> celigo guardrails replace-connection <id> <newConnectionId>

Debug

调试

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

Discovery

发现

celigo account search "<keyword>" celigo templates marketplace


<!-- TIER:3 -->

celigo account search "<keyword>" celigo templates marketplace


<!-- TIER:3 -->

Pre-Submit Checklist

提交前检查清单

Required (AI Agent)

必填项（AI Agent）

```
adaptorType
```
is exactly
```
AiAgentImport
```
(case-sensitive)
```
aiAgent.provider
```
is set (
```
"openai"
```
or
```
"gemini"
```
)

Instructions are set (

aiAgent.openai.instructions

aiAgent.litellm._overrides.gemini.systemInstruction

)

Model is set (

aiAgent.openai.model

aiAgent.litellm.model

)

If using

json_schema

output: schema is defined in

output.format.jsonSchema

(OpenAI) or

responseFormat.jsonSchema

(Gemini)

```
adaptorType
```
严格为
```
AiAgentImport
```
（区分大小写）
```
aiAgent.provider
```
已设置（
```
"openai"
```
或
```
"gemini"
```
）

已设置指令（

aiAgent.openai.instructions

或

aiAgent.litellm._overrides.gemini.systemInstruction

）

已设置模型（

aiAgent.openai.model

或

aiAgent.litellm.model

）

若使用
```
json_schema
```
输出：已在
```
output.format.jsonSchema
```
（OpenAI）或
```
responseFormat.jsonSchema
```
（Gemini）中定义Schema

Required (Guardrail)

必填项（防护栏）

```
adaptorType
```
is exactly
```
GuardrailImport
```
(case-sensitive)

guardrail.type

is set (

"ai_agent"

"pii"

, or

"moderation"

)

Sub-type config is present:

guardrail.pii.entities[]

for PII,

guardrail.moderation.categories[]

for moderation,

guardrail.aiAgent{}

for AI validation

```
adaptorType
```
严格为
```
GuardrailImport
```
（区分大小写）

guardrail.type

已设置（

"ai_agent"

"pii"

或

"moderation"

）

已存在子类型配置：PII类型需

guardrail.pii.entities[]

，内容审核需

guardrail.moderation.categories[]

，AI验证需

guardrail.aiAgent{}

Cross-resource consistency

跨资源一致性

If using BYOK:
```
_connectionId
```
references a valid HTTP connection with the provider's API key
If using MCP tools:
```
_mcpConnectionId
```
references a valid MCP connection
If using Celigo Tools:
```
_toolId
```
references a valid Tool resource
If response mapping needed: configured on the flow's
```
pageProcessors[]
```
entry, not on the agent itself

若使用BYOK：
```
_connectionId
```
引用了包含供应商API密钥的有效HTTP连接
若使用MCP工具：
```
_mcpConnectionId
```
引用了有效的MCP连接
若使用Celigo Tools：
```
_toolId
```
引用了有效的Tool资源
若需要响应映射：已在流程的
```
pageProcessors[]
```
条目上配置，而非在Agent本身配置

Gotchas

常见陷阱

PUT erases omitted fields. Always GET first, modify, then PUT. The
```
set
```
command handles this.
OpenAI and Gemini use different config paths. OpenAI instructions are at
```
aiAgent.openai.instructions
```
; Gemini instructions are at
```
aiAgent.litellm._overrides.gemini.systemInstruction
```
. Using the wrong path silently produces an agent with no instructions.
Gemini model IDs require the
gemini/
prefix. Use
```
gemini/gemini-2.5-pro
```
, not
```
gemini-2.5-pro
```
. Without the prefix, LiteLLM cannot route to the correct provider.
json_schema
output without a schema definition returns unpredictable JSON. Always define
```
jsonSchema
```
when using
```
json_schema
```
output format.
Response mapping is on the flow, not the agent. AI responses are available via
```
_json
```
in the flow's
```
pageProcessors[]
```
response mapping. Putting mapping config on the agent itself has no effect.
MCP tool connections must be type
mcp
. Regular HTTP connections cannot be used as
```
_mcpConnectionId
```
even if they point to an MCP server URL.
maxOutputTokens
defaults to 1000. For complex extractions or long-form generation, increase this or the response will be truncated silently.
Off-list models are silently swapped without BYOK. Selecting a model that isn't on Celigo's curated list when no BYOK connection is wired up makes the engine substitute the provider's default and surface a
```
model_correction
```
warning. Model-gated parameters the resolved model doesn't accept are also stripped (e.g.,
```
reasoning
```
on a
```
gpt-4.1
```
model,
```
thinkingConfig
```
on a non-thinking Gemini model). Read the returned warnings rather than assuming your requested model and parameters ran.
Unmapped inputs default to
record
. With no input mapping defined, the entire in-flight record is passed to the agent as
```
record
```
. Convenient for prototypes, but map
```
text
```
,
```
record
```
, or
```
files
```
explicitly for precise control over what the model sees.

PUT请求会清除未提及的字段。始终先执行GET请求，修改后再执行PUT请求。
```
set
```
命令会自动处理此问题。
OpenAI和Gemini使用不同的配置路径。OpenAI的指令位于
```
aiAgent.openai.instructions
```
；Gemini的指令位于
```
aiAgent.litellm._overrides.gemini.systemInstruction
```
。使用错误路径会导致Agent无指令，且无任何提示。
Gemini模型ID需要
gemini/
前缀。需使用
```
gemini/gemini-2.5-pro
```
，而非
```
gemini-2.5-pro
```
。若无该前缀，LiteLLM无法路由到正确的供应商。
无Schema定义的
json_schema
输出会返回不可预测的JSON。使用
```
json_schema
```
输出格式时，必须定义
```
jsonSchema
```
。
响应映射配置在流程上，而非Agent上。AI响应可通过流程
```
pageProcessors[]
```
响应映射中的
```
_json
```
获取。在Agent本身配置映射无效。
MCP工具连接必须为
mcp
类型。即使指向MCP服务器URL，常规HTTP连接也无法用作
```
_mcpConnectionId
```
。
maxOutputTokens
默认值为1000。对于复杂提取或长文本生成，需增大该值，否则响应会被静默截断。
未在列表中的模型会在无BYOK时被静默替换。当未配置BYOK连接时，选择Celigo精选列表外的模型会导致引擎替换为供应商的默认模型，并显示
```
model_correction
```
警告。已解析模型不支持的模型专属参数也会被移除（例如
```
gpt-4.1
```
模型的
```
reasoning
```
参数、非思考型Gemini模型的
```
thinkingConfig
```
参数）。需查看返回的警告，不要假设请求的模型和参数已生效。
未映射的输入默认使用
record
。若未定义输入映射，整个流转记录会作为
```
record
```
传递给Agent。原型开发时很方便，但为了精确控制模型接收的内容，需显式映射
```
text
```
、
```
record
```
或
```
files
```
。

Common Errors

常见错误

Error	Cause	Fix
422 `adaptorType invalid`	Wrong case	Use `AiAgentImport` or `GuardrailImport` exactly
Truncated AI response	`maxOutputTokens` too low	Increase to match expected response size
Empty or nonsensical output	Missing or vague instructions	Write specific instructions with expected input/output format
`_mcpConnectionId invalid`	Wrong connection type	Use an MCP connection, not HTTP
`_toolId not found`	Tool resource deleted or wrong ID	Verify tool exists with `celigo tools get <id>`
Guardrail flags everything	`confidenceThreshold` too low	Increase threshold (e.g., 0.7 to 0.9)
Guardrail misses obvious PII	Missing entity types	Add all relevant entity types to `guardrail.pii.entities[]`

错误	原因	修复方案
422 `adaptorType invalid`	大小写错误	严格使用 `AiAgentImport` 或 `GuardrailImport`
AI响应被截断	`maxOutputTokens` 值过小	根据预期响应大小增大该值
输出为空或无意义	指令缺失或模糊	编写明确的指令，包含预期的输入/输出格式
`_mcpConnectionId invalid`	连接类型错误	使用MCP连接，而非HTTP连接
`_toolId not found`	Tool资源已删除或ID错误	使用 `celigo tools get <id>` 验证Tool是否存在
防护栏标记所有内容	`confidenceThreshold` 值过低	提高阈值（例如从0.7调整到0.9）
防护栏遗漏明显的PII	实体类型缺失	将所有相关实体类型添加到 `guardrail.pii.entities[]`

configuring-ai-agents

Original

Translation

Configuring AI Agents

配置AI Agent

Two Types of AI Import

两种AI导入类型

AI Agent Imports

AI Agent导入项

Guardrail Imports

防护栏导入项

Quick Reference

快速参考

Adaptor Decision Matrix

适配器决策矩阵

Provider Decision Matrix

供应商决策矩阵

Minimum Required Fields

必填字段

Schema Index

Schema索引

Input Fields

输入字段

Output Formats

输出格式

Related Skills

相关技能

How to Build an AI Agent

如何构建AI Agent

1. Determine the task

1. 确定任务

2. Check for existing patterns

2. 检查现有模式

Search for existing AI agents in the account

搜索账户中已有的AI Agent

Search across the entire account

搜索整个账户

3. Choose the provider and model

3. 选择供应商和模型

4. Write the instructions

4. 编写指令

5. Configure the output format

5. 配置输出格式

6. Tune parameters

6. 调优参数

7. Add tools (if needed)

7. 添加工具（如有需要）

8. Configure BYOK (optional)

8. 配置BYOK（可选）

9. Build the JSON

9. 构建JSON

Celigo AI vs BYOK

Celigo AI vs BYOK

Conversation History

会话历史

Capability Check Before Building

构建前的能力检查

How to Build a Guardrail

如何构建防护栏

1. Choose the guardrail type

1. 选择防护栏类型

2. Set the confidence threshold

2. 设置置信度阈值

3. Build the JSON

3. 构建JSON

CLI Commands

CLI命令

CRUD -- AI Agents

CRUD -- AI Agents

Invoke (test without creating a job)

调用（无需创建任务即可测试）

Clone and connection management

克隆和连接管理

Debug

调试

CRUD -- Guardrails

CRUD -- 防护栏

Invoke (test without creating a job)

调用（无需创建任务即可测试）

Clone and connection management