Once you’ve built a reusable AI agent, you can incorporate it into multiple flows and APIs, very much like you would any import resource. In the steps below, you will also define the agent’s purpose, specify the model it uses, set its output format, and determine any tools it will have access to.
Create an agent from either location:
-
AI studio: Navigate to AI studio → AI agents → Create AI agent.
If you have previously created an agent and wish to create a new agent, then click + Create AI agent at the upper right side of the page.
-
Flow builder: In your flow, click the + icon to Add AI agent. Start your own, or choose from a list of prebuilt agents.
Name your agent: Provide a clear and unique agent name.
Description (optional): Enter a clear and concise description of your AI agent to help others understand its purpose. Keep this description updated as you make changes.
Type: Select the AI model source based on your requirement:
- Celigo AI (Celigo-managed): Select from Celigo-provided models. Celigo manages the provider and availability of supported models.
-
Bring your own key (BYOK): If you prefer to use your own connection (BYOK), you can select an OpenAI, Gemini or Anthropic connector. Celigo automatically lists all models compatible and accessible on that connection.
Note
Supported models vary by provider:
- OpenAI – gpt-4.1 and later
- Gemini – 2.5 and later
- Anthropic – Sonnet, Haiku, and Opus
You can choose from a curated list of AI models running under a Celigo-managed account, which includes the following options:
- OpenAI – gpt-5, gpt-5-pro, gpt-5-mini, gpt-5-nano, gpt-5.4, gpt-5.4-pro, gpt-4.1, gpt-4.1-mini (default), and gpt-4.1-nano
- Gemini – gemini-2.5-pro, gemini-2.5-flash-lite, gemini-2.5-flash, and gemini-2.5-flash-image
- Anthropic - claude-sonnet-5, claude-sonnet-4-6, claude-opus-4-8, claude-opus-4-8, and claude-opus-4-7, and claude-haiku-4-5
Note
If you switch to a different model, you may lose the configuration settings.
If you prefer to use your own connection (BYOK), you can select an OpenAI, Gemini or Anthropic connector.
Note
If you create a Gemini, OpenAI, or Anthropic connection and use it in an AI agent, then that connection doesn't count toward your endpoint entitlement. If the same connection is also used in an integration, it counts as a single endpoint.
The required AI Model field is then enabled for selecting an available model for that connection.
Note
If you switch to a different agent type, you may lose the configuration settings and the unsaved changes will be removed.
AI model advanced settings
For both Celigo AI and BYOK, select the settings icon next to AI model selection to open AI model advanced settings and fine-tune how the selected model generates responses.
It dynamically appear based on the selected model and the output formats it supports. Only the configurations applicable to that model type are displayed.
- Temperature: Control how varied or consistent the model’s responses are. Higher values produce more creative, less predictable output. Lower values produce more focused, repeatable output. Slide it 0 when you need deterministic results for extraction or Q&A. (This option is not available for gemini-2.5-flash-image.)
- Top_P: An alternative way to control randomness (nucleus sampling). Lower values make outputs more focused while higher values allow more variation.
-
Service tier: Sets the request priority level for calling the model. (This option is available only for BYOK.)
-
Verbosity: Control the level of detail in the model’s responses. For example, Medium provides a balanced response with sufficient context while keeping the output concise and usable for downstream steps.
- Max tokens: Set the maximum length of the model’s output. This limit is also constrained by the selected model’s context window.
- Seed: Control the randomness of the agent’s output with a numeric value to reproduce consistent results using the same input and configuration. (This option is available only for Gemini.)
- Top K: Limit token sampling to the top K highest-probability next-token candidates at each step of generation. Lower values produce more deterministic outputs, while higher values allow greater variation within the top-ranked choices.
- Includes reasoning: When enabled, the response includes an explanation of how the assistant arrived at the answer.
-
Reasoning effort: Control how extensively an agent analyzes and processes a task before generating a response.
Write your prompt
Instructions: Write clear, specific instructions that tell the agent what to do for each record. Detailed instructions ensure predictable and accurate outcomes.
You can drag the Instructions panel to reposition it while writing your instructions, making it easier to view other configuration details.
Important
Provide the intent and requirements for how the agent should operate, with a few examples. Clear instructions reduce ambiguity, control decision-making, and align behavior with the task. They guide the agent on task approach, rules, constraints, and action priorities.
Define how the AI model responds by choosing the output format:
- Plain text: Returns a text response. Select plain text for summaries, explanations, classifications, or human-readable output.
-
JSON: Returns structured output that will match a schema you define, the best option when downstream mapping or logic depends on consistent fields.
-
Name: For JSON output schemas, enter a schema name without spaces. Use only letters (a–z, A–Z), numbers (0–9), underscores (_) or hyphens (-).
Note
This option is not available for the Celigo AI model type gemini-2.5-flash-image.
-
Create schema: You can add multiple properties by providing a name and selecting a Data type from the list.
Hover on a property for additional options:
-
Additional settings: Click the gear icon to open Additional settings and configure validations. Learn more about Additional settings - field reference, JSON schema validation, and Manual schema validations
- Add property: Click the + icon to create a new property
- Delete property: Click the delete icon to remove a property
-
-
-
Image: Select this option for an image response (only for models capable of generating an image).
Note
In Gemini, this option is available only when you select the model type gemini-2.5-flash-image.
AI agents rely on tools to execute goals, which are the specific actions that you define for the agent to perform. Tools provide access to capabilities that invoke APIs through standardized inputs and outputs.
Note
When selecting any Gemini models, you can choose to use either MCP or non-MCP tools.
By selecting specific tools during agent creation, you effectively enhance an agent’s capabilities. Tools define how the agent exhibits predictable behavior, maintain secure access to necessary functions, and allow for the reuse of logic across related requirements.
Important
Tools are not available if you select Celigo AI model type gemini-2.5-flash-image.
-
Click + Add.
- The Add capabilities panel opens.
- Select one or more tools by browsing the list or searching for them.
-
Use the toggle at the top of the page and switch to MCP connections, then select or search for the connections you want to add.
Note
If no MCP connections are listed, click + Create MCP connection to add one.
- Expand the connection to view or select to add available tools, resources, and prompts and click Save.
After adding the tools, you can configure each tool by clicking its gear icon or remove it using the delete icon.
You can control what the Celigo AI agent can do by choosing the tools it’s allowed to use. When you configure an agent, you can add OpenAI tools and MCP tools available through connected MCP servers.
During execution, the flow checks each tool request and retries any temporary errors. Minimal execution is intended to keep the agent’s behavior predictable, reduces surprises, and increase the safely of your flow.
Add tools offers two default OpenAI options: Web search and Image generation. When you select either tool, you can configure it when you save your options and return to the Create AI agent panel. These prebuilt tools make sure your interactions are consistent, relevant, and secure, since the agent looks at and uses only the information sources that are right for the job.
Web search settings define the scope and context of the AI model’s searches. You can limit searches to specific websites and include location details, such as country, region, city, and timezone.
- Search only in these websites: You can input details for one or multiple websites to initiate a search.
- Country: Select a country to restrict the origin of information.
- Region: Enter the region name for which you intend to manage the origin of information.
- City: To further refine your search, enter a specific city.
- Timezone: Select the correct zone based on the location.
- Search context size: Select one of the following options: high, medium, or low. The amount of information used by the AI agent is based on this level.
When an AI agent has been instructed to create an image, configuring this tool helps you control how image outputs are generated by the AI model. Define the image size, quality, format, and background type as needed. Proper configuration ensures the generated images meet your visual and performance requirements.
- Size : Select resulting image size, in pixels (width * height).
- Quality: Select the relative image quality level.
- Format: Select a standard image output type.
- Background: Choose an opaque or transparent background.
Code execution tool (BYOK)
Code execution lets your AI agent write and run code mid-task to process data, do calculations, and generate files, using your own model provider key (BYOK). The agent can, for example, run a calculation and hand back a chart or a cleaned-up dataset, all within one agent run.
This feature only works with BYOK connections. It's not available for Celigo managed models. On Anthropic, the tool is labeled (Beta).
Adding the tool to your agent
Navigate to AI studio → AI agents → click to open an agent.
- In the Edit agent page, select a BYOK connection and model.
- Go to the Tools & capabilities panel and click Add.
- If the model supports code execution, you'll see the tool listed.
- Select it and add it to your agent like any other tool.
If the tool doesn't appear, your selected model likely doesn't support it yet. Switch to a supported model from the model list.
Provider specific behavior to know about
Each provider runs code in its own managed sandbox, with its own session behavior and execution limits:
| Provider | Session/state behavior | Execution limit | Pre-installed libraries |
|---|---|---|---|
| OpenAI / Azure OpenAI | 1-hour session; state clears once it expires | Set by the provider | Set by the provider |
| Anthropic | Scoped per API call — nothing carries over between turns | Set by the provider | Python 3.11, pandas, numpy, matplotlib |
| Gemini | Resets every turn | 30 seconds per execution, up to 5 executions per call | numpy, pandas, matplotlib |
Keep this in mind when writing agent instructions, code that needs to run long or persist state across turns won't work as expected within these limits.
None of the providers allow outbound network access from the sandbox, code can't call external APIs or fetch data from the internet.
Cost and billing
Every execution is recorded as an AI action, attributed to the correct provider. Because this is BYOK, AI credits are not charged, execution cost is billed to your own provider account, not through Celigo.
OpenAI / Azure OpenAI |
Anthropic |
Gemini | |
|---|---|---|---|
| Language | Python | Python + Bash | Python only |
| Pre-installed libraries | Provider-managed | Python 3.11, pandas, numpy, matplotlib | numpy, pandas, matplotlib |
Configure the AI agent
When you create an agent, only the essentials (such as Instructions and model Type) are required. Everything else defaults to safe, usable settings.
If you don’t explicitly override the following settings, their default values apply:
- Input: Mapper 2.0 values for this step
- Output: Text mode
- AI model selection: gpt-4.1-mini (for Type: Celigo AI only)
- Advanced settings: Secure platform-defined defaults
Click Save & close. After saving, the agent becomes available in the resource listing and can be reused.
Advanced
Click Advanced to expand this section (collapsed by default) and select one of the following options below One to many:
- Select Yes (advanced) if a single source record needs to internally create multiple destination records (e.g., an order with multiple line items).
Path to many: If you're processing JSON objects, select or enter the JSON path to the child records. Not needed for array- or row-based data. Only applies when One to many is set to Yes (advanced). - Select No (default) to leave the agent import behaving as it does today. This option can't be used when importing a CSV file.
Note
If the JSON path is misspelled or invalid, the flow run succeeds but shows a success count of 0. See Create a one-to-many import and access nested arrays for full behavior, including nested arrays.