Name: configuring-ai-agents
Author: celigo

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 1,000,000 characters on the built in providers). 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 as {"fields": [{"extract": " json.category", "generate": "category"}]} , but planned when building the agent. A json schema response is available via json AI agents do not require a connectionId unless using BYOK (bring your own key). Without one, built in providers use platform managed credentials; catalog providers are BYOK only and require one. Used across flows, APIs, and tools. An agent has no trigger or schedule of its own: it runs when one of those hands it a record, or when a chat request sends it a message. A request like "every morning" or "whenever an order arrives" needs the parent flow built too, with the agent as one of its steps. AI Agent Imports Invoke an LLM for classification, extraction, summarization, translation, or generation. aiAgent.provider takes any value in the enum in [aiagent.yml](references/schemas/aiagent.yml), and providers come in two families with different config formats: Built in providers each has its own config block and runs on Celigo AI or BYOK credentials: OpenAI ( provider: "openai" ) GPT models via the OpenAI Responses API, configured in aiAgent.openai{} . Supports reasoning effort control, structured JSON output, web search, MCP tools, Celigo Tools, and image generation. LiteLLM backed providers such as Gemini ( provider: "gemini" ) and Anthropic Claude ( provider: "anthropic" ) configured in aiAgent.litellm{} , with provider specific settings under litellm. overrides.<provider . Gemini adds Google Search grounding, URL context, and file search. Catalog providers the rest of the enum. They share a generic flat format ( model , modelOptions , instructions , output , and the tool arrays directly on aiAgent ) and are BYOK only : saving one without a connectionId fails with 422 connection required . The provider decides the format a block that doesn't match fails the save with 422 invalid provider config format . Agent or Guardrail? Pick by what the LLM produces. A guardrail ( GuardrailImport ) renders a verdict ( flagged: true false ) 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. Everything about building one the pii , moderation and ai agent types, masking, input modes, thresholds, its CLI commands and errors is in [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) A verdict to route on: PII, moderation, or a policy check GuardrailImport guardrail{} [configuring guardrails](../configuring guardrails/SKILL.md) adaptorType is case sensitive : AiAgentImport , not aiagentimport . Provider Decision Matrix Provider Config path Instructions field Model field Credentials openai aiAgent.openai{} openai.instructions openai.model Celigo AI or BYOK gemini , anthropic aiAgent.litellm{} (+ litellm. overrides.<provider ) litellm. overrides.<provider .systemInstruction litellm.model Gemini ids are stored without a gemini/ prefix Celigo AI or BYOK Catalog providers (the rest of the enum) Flat on aiAgent aiAgent.instructions aiAgent.model BYOK only Model fields are open strings [aiagent.yml](references/schemas/aiagent.yml) carries current examples and each block's tools[].type enum lists the tool types that provider supports. Minimum Required Fields AiAgentImport: name , adaptorType: "AiAgentImport" , aiAgent.provider , and the provider's config ( aiAgent.openai{} , aiAgent.litellm{} , or the flat catalog format). Instructions and model are required within it; catalog providers also need connectionId . 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 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. Which types the model can read depends on the account's document processing setting (below the table) conversationHistoryId string Stable per conversation identifier that retains and replays history across runs (see [Conversation History]( conversation history)) A mapped record with none of text , record or files is sent whole, as JSON. So with no input mapping the agent gets the in flight record as JSON unless the record has its own top level text , record or files field, which is then its only input; map explicitly when records carry one. An agent's input mapping is Mapper 2.0 mappings rows. With inputContext: "envelope" their extract paths read the run's envelope ( $.record.<field , $.settings.<field ) instead of the bare record. As on other imports, hooks.preMap , hooks.postMap and hooks.postSubmit can reshape records around the model call; agents have no postAggregate hook (see [writing scripts](../writing scripts/SKILL.md)). What files can read depends on the account's Intelligent document processing setting (My Account Company AI settings). It's off by default and account wide; only an owner or administrator can change it, in the UI; and an API token can't read it, so ask the user. With it off, the model's own file support decides: PDFs, PNG, JPG and WEBP images, and text are supported, and other types can fail the record (TIFF does). With it on, Celigo extracts text and tables from PDFs, scans and office files before the model sees them, and charges the extraction in AI credits. 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 guardrails](../configuring guardrails/SKILL.md) guardrail steps that flag records (PII, moderation, policy checks), often placed before or after an agent [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; when the result is only pass or fail, see [Agent or Guardrail?]( agent or guardrail)), generation (translations, summaries), enrichment (web search augmentation). The task determines the provider, model, output format, and whether tools are needed. Decide, too, which records need the model at all. An input filter on the agent step ( filter , as on any import; see [configuring filters](../configuring filters/SKILL.md import filter import filter)) skips the model for the rest, and it is the cheapest cost control. Skipped records still continue down the flow with the agent's response mapped fields empty, so give every later step that writes those fields its own filter, such as ["notempty", ["string", ["extract", "ai category"]]] . To judge each item of an array on its own (each order line, say), set oneToMany: true and pathToMany to the array's field on the agent. Each item then becomes its own record and its own billed model call, carrying the parent's other fields under PARENT , and the items are joined back into the parent record, with their response mapped fields, before the next step ([one to many.yml](references/common schemas/one to many.yml)). 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, and Anthropic when the user wants Claude. Use a catalog provider only when the user brings that vendor's API key. Within each provider, choose the model based on the task complexity: Simple tasks (classification, routing): use the provider's smaller, faster models Complex tasks (multi step reasoning, extraction): use its larger models Cost sensitive : smaller models process faster and cost less On Celigo AI (no BYOK connection) the model must be one the platform hosts for that provider, and the save checks it: a create or update with any other model fails with 422 Model "<model " is not supported. Please choose a supported model and test