Articles in this section

Create an AI agent

Teena Killa
Updated

An AI agent is a reusable resource that sends each record in a flow or API to an AI model, along with your instructions, and returns the model's response. Use one to classify, summarize, extract, or generate data without writing code. When you create an agent, you define its purpose, choose the model it uses, set its output format, and select the tools it can access. After you save it, you can add the agent to any number of flows and APIs, the same way you reuse an import.

You can create an agent from either location:

  • AI studio – Go to AI studio > AI agents, and then select Create AI agent. If your account already has agents, select + Create AI agent at the upper right of the page.

    The AI agents page in AI studio, showing the Create AI agent option.

  • Flow builder – In your flow, select the + icon, and then select Add AI agent. Start a new agent, or choose one of the prebuilt agents.

    The flow builder menu showing the Add AI agent option.

General

The General section identifies the agent and sets the source of its AI model.

  • Name your agent - A clear and unique name for the agent.
  • Description (optional) - A short summary of the agent's purpose, so other builders understand what it does. Update it when you change the agent.
  • Type - Where the agent's AI model comes from:
    • Celigo AI (Celigo managed) - Use a model from a Celigo managed account. Celigo manages the provider and the models available. Agent runs use your account's AI credits. See Type: Celigo AI.
    • Bring your own key (BYOK) - Use a model through your own connection to a supported AI provider. Your AI provider bills you directly, and Celigo AI credits aren't used. See Type: Bring your own key.

Type: Celigo AI

With Celigo AI, you select a model from a curated list that runs under a Celigo-managed account. You don't need a connection or an API key. The default model is gpt-4.1-mini.

The following models are available with Celigo AI:

  • OpenAI – gpt-5.6-sol, gpt-5.6-terra, gpt-5.6-luna, gpt-5.5, gpt-5.5-pro, gpt-5.4, gpt-5.4-pro, gpt-5, gpt-5-pro, gpt-5-mini, gpt-5-nano, gpt-4.1, gpt-4.1-mini (default), and gpt-4.1-nano
  • Google Gemini – gemini-2.5-pro, gemini-2.5-flash, gemini-2.5-flash-lite, and gemini-2.5-flash-image
  • Anthropic – claude-sonnet-5, claude-sonnet-4-6, claude-opus-4-8, claude-opus-4-7, and claude-haiku-4-5

To track how many AI credits your agents use, see Track your AI agent credits.

Note

If you switch to a different model, you may lose the agent's configuration settings.

The confirmation shown when you switch models.

Type: Bring your own key

With Bring your own key (BYOK), the agent uses a model through your own connection to an AI provider, and your provider account is billed for the runs. Select a connection to one of the following providers, and then select a model in the AI model field. integrator.io lists only the models that are compatible with the connection and that your provider account can access. Each provider name links to the article that explains how to set up its connection.

Providers available with Celigo AI and BYOK

  • OpenAI - gpt-5.6-sol, gpt-5.6-terra, gpt-5.6-luna, gpt-5.5, gpt-5.5-pro, gpt-5.4, gpt-5.4-pro, gpt-5.2, gpt-5.2-pro, gpt-5.1, gpt-5, gpt-5-pro, gpt-5-mini, gpt-5-mini-2025-08-07, gpt-5-nano, gpt-4.1, gpt-4.1-mini, gpt-4.1-mini-2025-04-14, gpt-4.1-nano, gpt-4.1-nano-2025-04-14, gpt-4o, gpt-4o-2024-11-20, gpt-4o-mini, o4-mini, o3, o3-pro, o3-mini, o1, and o1-pro
  • Google Gemini - gemini-3.8-flash, gemini-3.7-flash, gemini-3.6-flash, gemini-3.5-flash, gemini-3.5-flash-lite, gemini-3.1-flash-lite, gemini-3.1-flash-image, gemini-3-pro-image, gemini-2.5-pro, gemini-2.5-flash, gemini-2.5-flash-lite, and gemini-2.5-flash-image
  • Anthropic - claude-opus-5, claude-sonnet-5, claude-opus-4-8, claude-opus-4-7, claude-sonnet-4-6, and claude-haiku-4-5-20251001

Note

Access to Gemini 2.5 models through BYOK depends on your Gemini account. Accounts that used Gemini 2.5 models before may keep access, while new accounts may not. If a Gemini 2.5 model isn't available to your account, the agent run fails with a 404 not found error. Select a Gemini 3.x model instead.

Providers available with BYOK only

  • Groq - GPT-OSS 20B (openai/gpt-oss-20b), GPT-OSS 120B (openai/gpt-oss-120b), GPT-OSS Safeguard 20B (openai/gpt-oss-safeguard-20b), Qwen3.6 27B (Vision) (qwen/qwen3.6-27b), and Compound (groq/compound)
  • Mistral - Mistral Large 3 (mistral-large-2512), Mistral Medium 3.5 (mistral-medium-2604), Mistral Small 4 (mistral-small-2603), Ministral 3 14B (ministral-14b-2512), Ministral 3 8B (ministral-8b-2512), Codestral (codestral-2508), and GLM 5.2 (glm-5-2)
  • DeepSeek - DeepSeek V4 Flash (deepseek-v4-flash) and DeepSeek V4 Pro (deepseek-v4-pro)
  • Hugging Face – Llama 3.1 8B Instruct (meta-llama/Llama-3.1-8B-Instruct), Llama 3.3 70B Instruct (meta-llama/Llama-3.3-70B-Instruct), DeepSeek R1 (deepseek-ai/DeepSeek-R1), Qwen2.5 72B Instruct (Qwen/Qwen2.5-72B-Instruct), Qwen3 14B (Qwen/Qwen3-14B), and Gemma 3 12B IT (google/gemma-3-12b-it)
  • xAI - Grok 4.6 (grok-4.6), Grok 4.5 (grok-4.5), and Grok 4.3 (grok-4.3)
  • Cohere - Command A 03 2025 (command-a-03-2025), Command R Plus 08 2024 (command-r-plus-08-2024), Command R 08 2024 (command-r-08-2024), and Command R7b 12 2024 (command-r7b-12-2024)
  • Together AI (Agents) - GPT-OSS 120B (openai/gpt-oss-120b), Llama 3.3 70B Instruct Turbo (meta-llama/Llama-3.3-70B-Instruct-Turbo), DeepSeek V4 Pro (0813) (deepseek-ai/DeepSeek-V4-Pro-0813), DeepSeek V4 Flash (0731) (deepseek-ai/DeepSeek-V4-Flash-0731), DeepSeek V4.1 Flash (deepseek-ai/DeepSeek-V4.1-Flash), GLM-5.3 (zai-org/GLM-5.3), GLM-5.3 Flash (zai-org/GLM-5.3-Flash), GLM-5.2 (zai-org/GLM-5.2), Kimi K3 (moonshotai/Kimi-K3), MiniMax M3 (MiniMaxAI/MiniMax-M3), and Qwen3.5 9B (Qwen/Qwen3.5-9B)
  • Fireworks AI (Agents) - GPT-OSS 120B (gpt-oss-120b), GLM-5.3 (glm-5p3), GLM-5.3 Flash (glm-5p3-flash), GLM-5.2 (glm-5p2), Kimi K3 (kimi-k3), Kimi K2.6 (kimi-k2p6), MiniMax M3 (minimax-m3), MiniMax M2.7 (minimax-m2p7), and Nemotron 3 Ultra (nemotron-3-ultra-nvfp4)
  • Azure OpenAI (Agents) - GPT-5 (gpt-5), GPT-5 Mini (gpt-5-mini), GPT-5 Nano (gpt-5-nano), GPT-5.1 (gpt-5.1), GPT-5.2 (gpt-5.2), GPT-4.1 (gpt-4.1), GPT-4.1 Mini (gpt-4.1-mini), GPT-4.1 Nano (gpt-4.1-nano), GPT-4o (gpt-4o), GPT-4o Mini (gpt-4o-mini), GPT-OSS 120B (gpt-oss-120b), and Phi-4 Mini Reasoning (Phi-4-mini-reasoning)
  • AWS Bedrock (Agents) - Claude Sonnet 4.6 (global.anthropic.claude-sonnet-4-6), Claude Opus 4.6 (global.anthropic.claude-opus-4-6-v1), Claude Sonnet 4.5 (global.anthropic.claude-sonnet-4-5-20250929-v1:0), Claude Haiku 4.5 (global.anthropic.claude-haiku-4-5-20251001-v1:0), Claude Opus 4.5 (global.anthropic.claude-opus-4-5-20251101-v1:0), and Nova 2 Lite (global.amazon.nova-2-lite-v1:0)
  • NVIDIA NIM - GPT-OSS 20B (openai/gpt-oss-20b), Nemotron 3 Ultra 550B (nvidia/nemotron-3-ultra-550b-a55b), Nemotron 3 Super 120B (nvidia/nemotron-3-super-120b-a12b), Nemotron 3.5 Lightning 30B (nvidia/nemotron-3.5-lightning-30b-a3b), and Nemotron 3 Nano Omni 30B (nvidia/nemotron-3-nano-omni-30b-a3b-reasoning)
  • Ollama Cloud - Nemotron 3 Nano 30B (nemotron-3-nano:30b), Nemotron 3 Super (nemotron-3-super), Nemotron 3 Ultra (nemotron-3-ultra), GPT-OSS 20B (gpt-oss:20b), and GPT-OSS 120B (gpt-oss:120b)
  • Google Vertex AI - Gemini 2.5 Pro (gemini-2.5-pro), Gemini 2.5 Flash (gemini-2.5-flash), and Gemini 2.5 Flash-Lite (gemini-2.5-flash-lite)

Notes

  • Some models display lifecycle labels, such as Migration recommended or Retiring on date, indicating that they're approaching retirement. You can continue using these models until their retirement date. To avoid failed runs, switch to a supported model before then. Retired models are unavailable for new AI agents, and existing agents that use a retired model can't run until you select a supported model. See Understand AI model lifecycle labels.
  • A Google Gemini, OpenAI, Mistral, or Anthropic connection that you use only in AI agents doesn't count toward your endpoint entitlement. If you also use the same connection in an integration, it counts as one endpoint.
  • If you switch to a different agent type, you may lose the agent's configuration settings, and unsaved changes are removed.
    The confirmation shown when you switch the agent type.

AI model advanced settings

AI model advanced settings fine-tune how the selected model generates responses, for both Celigo AI and Bring your own key agents. To open them, select the settings icon next to AI model selection. Only the settings that the selected model supports appear.

The AI model advanced settings panel.

  • Temperature - How varied the responses are. Higher values give more creative, less predictable output; lower values give more focused, repeatable output. Set it to 0 for repeatable results, such as data extraction or question answering. Not available for gemini-2.5-flash-image.
  • Top_P - Controls randomness through nucleus sampling. Lower values give more focused output; higher values allow more variation.
  • Top K - Limits each step of generation to the K most likely next tokens. Lower values give more predictable output; higher values allow more variation.
  • Seed - A number that makes output repeatable when you use the same input and configuration. Available only for Google Gemini models.
  • Max tokens - The maximum length of the response. The model's context window also limits it.

  • Verbosity - How detailed the response is. For example, Medium gives enough context while keeping output short enough for later flow steps.

    The Verbosity setting.

  • Reasoning effort - How much the model analyzes a task before it responds.

    The Reasoning effort setting.

  • Includes reasoning - When turned on, the response explains how the model reached its answer.

  • Service tier - The priority level of requests sent to the model. Available only for Bring your own key.

    The Service tier setting.

Write your prompt

The Instructions field tells the agent what to do with each record. Clear, specific instructions give predictable, accurate results.

In Instructions, describe:

  • The task and its goal.
  • The rules and constraints the agent must follow.
  • Which actions take priority when the agent has to choose.
  • A few examples of input and the output you expect.

You can drag the Instructions panel to another position so you can see other settings while you write.

The Instructions panel moved beside the agent settings.

Output format

The output format decides how the agent returns its response to your flow. For how each format is validated and passed to later steps, see Output for Celigo AI agents.

  • Plain text (default) - Returns a text response. Use it for summaries, explanations, classifications, or other human-readable output.
  • JSON - Returns structured output that matches a schema you define. Use it when mappings or logic in later steps depend on consistent fields.
    • Name - A schema name with no spaces. Use only letters (a–z, A–Z), numbers (0–9), underscores (_), or hyphens (-). Not available for the Celigo AI model gemini-2.5-flash-image.

    • Create schema - Add properties to the schema. For each property, enter a name and select a Data type.

      The JSON schema settings with two properties.

      Hover over a property for more options:

      • Additional settings - Select the gear icon to add validations. See Introduction to Celigo tools for the field reference and validation options.

        The Additional settings panel for a schema property.

      • Add property - Select the + icon to add another property.
      • Delete property - Select the delete icon to remove the property.
  • Image - Returns an image. This option appears only for models that can generate images. For Google Gemini, it appears only when you select gemini-2.5-flash-image.

Tools & capabilities

Tools are specific actions the agent can take while it works on a record, such as searching the web or calling an API through an MCP connection. Adding only the tools a task needs keeps the agent's behavior predictable and limits what it can access. For more about tools, see Introduction to Celigo tools.

  • With Google Gemini models, you can use both MCP and non-MCP tools.
  • Tools aren't available for the Celigo AI model gemini-2.5-flash-image.

Add tools and MCP connections

  1. Under Tools & capabilities, select + Add. The Add capabilities panel opens.

    The Tools & capabilities section with the Add option.

  2. Browse or search for tools, and select one or more.

  3. To add MCP tools, switch the toggle at the top of the panel to MCP connections, and then select or search for connections. If no MCP connections are listed, select + Create MCP connection. See Create an MCP connection from an AI agent.

    The Create MCP connection option in the Add capabilities panel.

  4. Expand a connection to select its tools, resources, and prompts. See Add an MCP prompt to an agent.
  5. Select Save.

To change a tool's settings, select its gear icon. To remove a tool, select its delete icon.

Configure an AI agent tool

You control what the agent can do by choosing which tools it can use: built-in tools, and tools available through connected MCP servers. During a run, integrator.io checks each tool request the agent makes and automatically retries temporary errors.

Add tools includes built-in tools such as Web search, Image generation, and Google search. After you add one, configure it from the Create AI agent panel. These tools limit the agent to the information sources that suit the task.

Configure web search

The Web search tool lets the agent search the internet. Its settings limit where the agent searches and add location context.

The Web search settings.

  • Search only in these websites - One or more websites to limit the search to.
  • Country - The country to restrict information sources to.
  • Region - The region to restrict information sources to.
  • City - A city to narrow the search further.
  • Time zone - The time zone for the location.
  • Search context size - How much search information the agent uses: high, medium, or low.
Configure image generation

The Image generation tool lets the agent create images when its instructions ask for one. Its settings control the image the model produces.

The Image generation settings.

  • Size - The image size in pixels (width × height).
  • Quality - The relative image quality.
  • Format - The image file type.
  • Background - An opaque or transparent background.
Configure Google search

The Google search tool lets the agent search Google. Its settings set the time range of results.

  • Select a range - Select one of the listed ranges, select Apply, and then select Save.

    The Google search time range options.

  • Custom range - In Set custom range, select a start date and an end date, select Apply, and then select Save.

    The custom date range for Google search.

Code execution tool (BYOK)

The code execution tool lets the agent write and run code while it works on a record, for example to do calculations, clean up a dataset, or generate a chart or file. It's available only for Bring your own key agents, on models that support it. It isn't available for Celigo AI models. On Anthropic, the tool is labeled (Beta).

Adding the tool to your agent
  1. Go to AI studio > AI agents, and open the agent.
  2. Select a Bring your own key connection and a model.
  3. Under Tools & capabilities, select + Add.
  4. If the model supports code execution, you'll see the tool listed.
  5. Select the code execution tool, and then select Save.

If the code execution tool isn't listed, the selected model doesn't support it. Select a model that does.

Provider specific behavior to know about

Each provider runs code in its own sandbox, with its own session behavior and limits. None of the sandboxes allow outbound network access, so code can't call external APIs or download data. Write your instructions so that code finishes within the provider's limits and doesn't depend on state from an earlier turn.

Provider Languages Session and state Execution limits Pre-installed libraries
OpenAI Python One-hour session; state clears when it expires Set by the provider Set by the provider
Anthropic Python and Bash Limited to one API call; nothing carries over between turns Set by the provider Python 3.11, pandas, numpy, and matplotlib
Google Gemini Python Resets every turn 30 seconds per execution, up to five executions per call numpy, pandas, and matplotlib
Cost and billing

Each code execution is recorded as an AI action for its provider. Because the tool runs on your own key, your AI provider bills you for it, and Celigo AI credits aren't used. See Track your AI agent actions and credits usage.

Configure the AI agent

Only Instructions and Type are required to create an agent. Settings you don't change use these defaults:

  • Input - Mapper 2.0 values for this step.
  • Output - Plain text.
  • AI model selection - gpt-4.1-mini (Celigo AI only).
  • Advanced settings - Platform-defined defaults.

Select Save & close. The agent appears in the AI agents list, and you can add it to flows and APIs. To test it before you use it in a flow, see Preview an AI agent.

Advanced

The One to many setting decides whether one source record can produce multiple destination records, such as an order with several line items. Select Advanced to expand the section, which is collapsed by default, and then select an option under One to many:

  • Yes (advanced) - One source record can create multiple destination records.
    • Path to many - If you're processing JSON objects, select or enter the JSON path to the child records. You don't need a path for array-based or row-based data.
  • No (default) - Each source record is processed as one record.

Note

If the Path to many value is misspelled or invalid, the flow run succeeds but shows a success count of 0. For full behavior, including nested arrays, see Create a one-to-many import and access nested arrays.