Configuring AI Agents

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

Quick Reference

Adaptor Decision Matrix

adaptorType is case-sensitive: AiAgentImport, not aiagentimport.

Provider Decision Matrix

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

• 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

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:

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:

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

Related Skills

• configuring-imports > AI Imports -- how AI agents fit within the broader import category
• configuring-connections > Quick Reference -- MCP connections for tool use, HTTP connections for BYOK
• building-flows > How to Build a Flow -- wiring AI agents into flow pipelines
• building-tools > Tool Concepts -- building Celigo Tools that AI agents can invoke
• writing-mappings > Response Mapping Reference -- extracting fields from AI responses
• troubleshooting-flows > Diagnostic Workflow -- diagnosing AI agent failures