Configure Celigo AI agent and guardrail imports -- LLM-powered steps that classify, extract, validate, or generate data within flows. Use when creating agent imports (OpenAI, Gemini), guardrails (PII, moderation), or configuring prompts, structured output, or BYOK connections.

<! TIER:1 Configuring AI Agents 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. Two Types of AI Import AI Agent Imports 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. 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](../configuring guardrails/SKILL.md)). Quick Reference Adaptor Decision Matrix You need... Use adaptorType Config block Read schema LLM classification, extraction, generation AiAgentImport aiAgent{} [aiagent.yml](references/schemas/aiagent.yml) PII detection or masking GuardrailImport guardrail{} [guardrail.yml](references/schemas/guardrail.yml) Content moderation GuardrailImport guardrail{} [guardrail.yml](references/schemas/guardrail.yml) AI based custom validation GuardrailImport with guardrail.type: "ai agent" guardrail.aiAgent{} [guardrail.yml](references/schemas/guardrail.yml) + [aiagent.yml](references/schemas/aiagent.yml) adaptorType is case sensitive : AiAgentImport , not aiagentimport . Provider Decision Matrix 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 Minimum Required Fields AiAgentImport: name , adaptorType: "AiAgentImport" , aiAgent.provider , and provider config ( aiAgent.openai{} or 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{} ). 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) AI agent config: [aiagent.yml](references/schemas/aiagent.yml) provider, model, instructions, reasoning, temperature, output format, tools Guardrail config: [guardrail.yml](references/schemas/guardrail.yml) PII entities, moderation categories, AI based validation, confidence threshold 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]( conversation history)) If no input mapping is defined, the agent receives the un mapped in flight record as record by default. 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. Related Skills [configuring imports AI Imports](../configuring imports/SKILL.md ai imports) how AI agents fit within the broader import category [configuring connections Quick Reference](../configuring connections/SKILL.md quick reference) MCP connections for tool use, HTTP connections for BYOK [building flows How to Build a Flow](../building flows/SKILL.md how to build a flow) wiring AI agents into flow pipelines [building tools Tool Concepts](../building tools/SKILL.md tool concepts) building Celigo Tools that AI agents can invoke [writing mappings Response Mapping Reference](../writing mappings/SKILL.md response mapping reference transformation 10) extracting fields from AI responses [troubleshooting flows Diagnostic Workflow](../troubleshooting flows/SKILL.md diagnostic workflow) diagnosing AI agent failures [writing handlebars Quick Reference](../writing handlebars/SKILL.md quick reference) dynamic expressions in AI prompts and field values <! TIER:2 How to Build an AI Agent 1. Determine the task 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. 2. Check for existing patterns 3. Choose the provider and model 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 4. Write the instructions 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. 5. Configure the output format 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). 6. Tune parameters 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 7. Add tools (if needed) 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 8. Configure BYOK (optional) 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 . 9. Build the JSON Read the schema files from the [Schema Index]( schema index). Start with [request.yml](references/schemas/request.yml) for base fields, then [aiagent.yml](references/schemas/aiagent.yml) for the provider configuration block. 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 connec

configuring-ai-agents