Search for existing AI agents in the account

celigo ai-agents list

Search across the entire account

celigo account search "ai agent" celigo account search ""

### 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 your agent configuration.` The message doesn't list the hosted models, so don't pick names from memory -- use an example from [aiagent.yml](references/schemas/aiagent.yml) or the model of an existing working agent. With BYOK, a model off the hosted list saves and passes through to the provider as-is.

### 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. Where it goes depends on the provider family: `aiAgent.openai.output.format` (OpenAI), `aiAgent.litellm.responseFormat` (Gemini, Anthropic), or `aiAgent.output.format` (catalog providers), each holding `type: "json_schema"`, `name`, `strict` and `jsonSchema`. `litellm.responseFormat` holds them directly, with no `format` level inside it
- **`text`** -- free-form text response. Use for summarization, translation, or when the entire response is one field
- **`blob`** -- binary output (image generation use cases), on OpenAI and Gemini only: the save refuses it with 422 on Anthropic and on catalog providers

For `json_schema`, set `strict: true` if you need guaranteed schema conformance (slightly higher latency). On a built-in provider, when you write `jsonSchema` yourself, set `schemaMode: "json"` beside it and send it again on every full update: a PUT that omits it clears it, and without it the UI opens the schema in its visual editor, whose next save drops keywords that editor doesn't keep (`format`, `const`, `$ref`, `anyOf`, `additionalProperties`, ...) and turns `integer` into `number`. On OpenAI, a root-level `additionalProperties` is dropped from `jsonSchema` on save (nested ones stay) and strict runs still return conforming JSON, so don't chase it in a read-back.

### 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. OpenAI `-pro` models start at `"medium"`: `"low"` saves, but the run is refused. Claude's is `_overrides.anthropic.thinkingConfig`: `type: "enabled"` with `budgetTokens` (1024 or more; the save refuses `enabled` without it), or `type: "adaptive"` with an `effort`
- **`temperature`** -- `0.2` for deterministic output (data extraction, classification); up to `1.0` for creative generation. Anthropic accepts only 0 to 1 (a higher value fails the save); OpenAI and Gemini go up to 2. Leave `topK` off Claude models released after Claude Opus 4.6, which refuse it at run time
- **`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) / **`webSearch`** (Anthropic) -- search the web for current information to enrich records. Anthropic's takes `allowedDomains` or `blockedDomains`, not both
- **`code_execution`** (OpenAI) / **`codeExecution`** (Gemini, Anthropic) -- the provider's built-in code execution, on BYOK only: on Celigo AI the save accepts it, but the run is refused with 422 `Code Execution requires a BYOK connection.` Send only `{"type": ...}`, in the provider's spelling (the other one fails the save with 422)
- **`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

An MCP connection can also give the agent **prompts** (`"prompts": [{"type": "mcp", "mcp": {"_mcpConnectionId": "...", "allowedPrompts": ["..."]}}]`) and read-only **resources**, such as a policy document someone else maintains (`"resources": [{"type": "mcp", "mcp": {"_mcpConnectionId": "...", "allowedResources": [{"name": "...", "uri": "..."}]}}]`, at least one entry). Both sit beside `tools` in the provider's block. The save checks only their shape and that the connection exists, so copy prompt names and resource URIs from the server's catalog. The run does contact the server: when it can't be reached, each record fails with `mcp_connection_error` before the model is called.

### 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.

An Anthropic agent on the customer's own key, returning JSON. Everything the model needs sits in `aiAgent.litellm`:

```json
{
  "name": "Classify support tickets",
  "adaptorType": "AiAgentImport",
  "_connectionId": "<connection holding the Anthropic API key>",
  "aiAgent": {
    "provider": "anthropic",
    "litellm": {
      "model": "claude-sonnet-4-6",
      "temperature": 0.2,
      "maxCompletionTokens": 2000,
      "responseFormat": {
        "type": "json_schema",
        "schemaMode": "json",
        "name": "ticket_class",
        "strict": true,
        "jsonSchema": {
          "type": "object",
          "properties": {
            "category": {"type": "string", "enum": ["billing", "shipping", "other"]},
            "summary": {"type": "string"}
          },
          "required": ["category", "summary"],
          "additionalProperties": false
        }
      },
      "_overrides": {
        "anthropic": {"systemInstruction": "Classify the support ticket and summarize it in one sentence."}
      }
    }
  }
}

A Gemini agent is the same with provider: "gemini", a Gemini litellm.model and the instructions in _overrides.gemini.systemInstruction. An OpenAI agent puts model, instructions and output.format (the same type, name, strict and jsonSchema) in aiAgent.openai. Nothing goes flat on aiAgent for these three providers: aiAgent.model, aiAgent.instructions and aiAgent.output are the catalog providers' format.

Celigo AI vs BYOK

Cutting across the built-in providers is a second decision: run the agent on Celigo AI (platform-managed credentials) or BYOK (bring your own key). Catalog providers have no Celigo AI option -- they are always BYOK.

• Celigo AI -- no API key to manage. The trade is restriction: model choice is limited to the models the platform hosts for each provider (the save refuses any other), and runs are charged in AI credits against the account's prepaid AI-agent balance (aiAgentsPrepaidBalance in celigo subscriptions licenses), tool charges included. Once the balance reaches zero, runs are refused with 402 insufficient_credits. The account's AI agent actions are also counted per billing period, MCP tool calls and resource reads included (aiAgentsActionsUsage in celigo subscriptions entitlement-usage)
• BYOK -- the agent uses your own API key (configured on a connection; see step 8 above). Any model the provider supports is available -- new releases, fine-tuned models, models off Celigo's curated list -- and the provider bills the key's owner: the credit balance doesn't gate the run, and rate limits are your provider account's

Default to Celigo AI for prototyping, low-volume agents, and agents happy with the curated model list. Reach for BYOK when you need a model that isn't on the list, when volume would drain the prepaid credit balance, or when you want costs to land on your existing AI vendor billing.

Switching between Celigo AI and BYOK -- or changing the model -- can drop configuration that no longer applies: serviceTier is BYOK-only, reasoning.effort applies only to reasoning-capable models, and image modalities apply only to image-capable Gemini models. It is not a one-knob change.

Conversation History

By default, AI agent steps are stateless -- each record is its own conversation and the agent has no memory of previous records. This keeps behavior reproducible and cost predictable.

To make an agent stateful, map a stable per-conversation identifier into its conversationHistoryId input field -- a Slack thread ID, session UUID, customer ID, or ticket number, whatever is unique per conversation. Celigo retains the conversation history for that identifier and replays it on subsequent calls, so the agent sees prior turns. Mapping record.slack_thread_id, for example, makes every reply in a Slack thread aware of the earlier messages.

The identifier is scoped per user and per agent: the same string used by two different agents is two separate conversations, and the same agent used by two different users is two separate conversations. The retained history can't be read back through the API, and it doesn't appear in the agent's Conversation history in the UI, which lists only conversations started there -- it exists for the model to read, not for users to browse -- and idle conversations age out via a TTL that resets on each update.

Capability Check Before Building

Before building an agent, walk through each action the requirement says the agent should perform and confirm each one maps to a capability the agent will actually have at runtime. The goal is to surface gaps early, not to refuse capabilities.

Capabilities come from three places:

• Native to the chosen model -- OpenAI's web_search and image_generation; Gemini's googleSearch, urlContext, fileSearch, and image-modality output; Anthropic's webSearch; code execution on all three, with BYOK
• Tools wired into the agent -- mcp tools and Celigo Tools (MCP prompts and resources are read-only content, not actions)
• Downstream steps in the parent -- rendering output, writing to a destination, notifying a recipient (same shape whether the parent is a flow, API endpoint, or Tool)

For each action, ask which of the three covers it; if none do, that is a gap to raise before building. A common example is "generate a PDF invoice": no provider ships PDF rendering as a native capability, so the right shape is the agent emitting structured invoice content (json_schema output) with a downstream step or Celigo Tool rendering the PDF. Equally, don't enable capabilities the requirement didn't ask for -- "classify support tickets" needs text classification (native), not web_search "just in case."

CLI Commands

Invoking a saved agent, or previewing an agent document (invoke with no id, given {"import": <agent document>, "data": [records]}), creates no job, but it is a real run: the model is called and billed (in AI credits on Celigo AI; the key's owner pays on BYOK), and its tools (MCP servers, Celigo Tools, web search) act for real. Invoke an agent whose tools can write only with the user's go-ahead. A preview evaluates only the first record; invoke the saved agent by id to run several. To test the flow around it without calling the model, give the agent a mockResponse of result records ([{"statusCode": 200, "_json": {...}}], or _text for text output; any other shape fails the save with 422 Mock Response must be in integrator.io canonical format.) and test-run the flow (celigo flows test-run <flowId> --export <exportId>). The test run uses the mock instead of the model, so it costs nothing and proves nothing about the prompt.

Debug logs are captured by whatever runs the agent: celigo ai-agents enable-debug <id> opens a window of up to 60 minutes, and you read the requests from the flow, API or Tool that ran it (celigo flows debug-requests <flowId> <agentId>, or celigo apis debug-requests / celigo tools debug-requests). The chat routes (POST /v1/imports/{_id}/aiagents/chat for a saved agent, POST /v1/aiagents/chat for an unsaved document) and POST /v1/imports/preview/compare (several agent documents side by side on the same data) have no CLI command. A chat turn runs the agent alone, without its filter, mappings, hooks or response mapping, and like an invoke it is billed and its tools act.

# CRUD -- AI Agents
celigo ai-agents list
celigo ai-agents get <id>
celigo ai-agents create < agent.json
celigo ai-agents update <id> < agent.json
celigo ai-agents set <id> key=value [key2=value2 ...]
celigo ai-agents delete <id> [-y]

# Invoke: no job, but a real, billed run whose tools act
echo '[{"text":"classify this"}]' | celigo ai-agents invoke <id>

# Clone and connection management
celigo ai-agents clone <id>
celigo ai-agents replace-connection <id> <newConnectionId>

# Debug
celigo ai-agents enable-debug <id> [--duration <minutes>]
celigo ai-agents disable-debug <id>

# Discovery
celigo account search "<keyword>"
celigo templates marketplace

Pre-Submit Checklist

Required (AI Agent)

• adaptorType is exactly AiAgentImport (case-sensitive)
• aiAgent.provider is a value in the schema enum, and the config format matches it (openai{}, litellm{}, or the flat catalog format)
• Instructions are set (aiAgent.openai.instructions, aiAgent.litellm._overrides.<provider>.systemInstruction, or aiAgent.instructions for a catalog provider)
• Model is set (aiAgent.openai.model, aiAgent.litellm.model, or aiAgent.model) -- on Celigo AI, one the platform hosts
• Catalog provider: _connectionId points at a BYOK connection
• If using json_schema output: schema is defined in aiAgent.openai.output.format.jsonSchema (OpenAI), aiAgent.litellm.responseFormat.jsonSchema (Gemini, Anthropic; no format level), or aiAgent.output.format.jsonSchema (catalog providers), with type: "json_schema" and name beside it (and, on a built-in provider, schemaMode: "json" when you wrote the schema yourself)

Cross-resource consistency

• If using BYOK: _connectionId references a valid HTTP connection with the provider's API key
• If using MCP tools: _mcpConnectionId references a valid MCP connection
• If using Celigo Tools: _toolId references a valid Tool resource
• If response mapping needed: configured on the flow's pageProcessors[] entry, not on the agent itself

Gotchas

1. PUT erases omitted fields. Always GET first, modify, then PUT. The set command handles this.
2. Each provider family has its own config path. OpenAI instructions are at aiAgent.openai.instructions; Gemini and Anthropic instructions are at aiAgent.litellm._overrides.<provider>.systemInstruction; catalog providers use aiAgent.instructions. Using the wrong path silently produces an agent with no instructions.
3. Gemini model IDs have no gemini/ prefix. The platform stores them bare (gemini-2.5-flash), and the provider is already selected by aiAgent.provider.
4. json_schema output without a schema definition returns unpredictable JSON. Always define jsonSchema when using json_schema output format.
5. Response mapping is on the flow, not the agent. AI responses are available via _json in the flow's pageProcessors[] response mapping. Putting mapping config on the agent itself has no effect.
6. MCP tool connections must be type mcp. Regular HTTP connections cannot be used as _mcpConnectionId even if they point to an MCP server URL.
7. Output is capped at 5000 tokens unless you set it. An agent created without a cap is saved with 5000: maxOutputTokens on OpenAI, litellm.maxCompletionTokens on Gemini and Anthropic. Raise it for long extractions (the schema allows up to 128000; the model's own limit may be lower).
8. The save refuses a model the platform doesn't host. On Celigo AI (no BYOK connection), a create or update with an unhosted model fails with 422 Model "<model>" is not supported..., and nothing is swapped or corrected. The message doesn't list the hosted models: use the schema's examples or a working agent's model. With BYOK, a model off the hosted list saves and passes through to the provider as-is.
9. Unmapped inputs default to record. With no input mapping defined, the entire in-flight record is passed to the agent as record. Convenient for prototypes, but map text, record, or files explicitly for precise control over what the model sees.
10. A Claude agent's preview shows empty instructions. The preview's request stage carries "instructions": "" for an Anthropic agent; its prompt travels in _overrides.anthropic.systemInstruction and is applied. Don't read the empty field as a missing prompt.
11. Some settings save and fail only when the agent runs. The save checks shape, the hosted model and a few provider rules, not every model's limits: reasoning.effort: "low" on an OpenAI -pro model saves and the run is refused (Supported values are: 'medium', 'high', and 'xhigh'), and so are topK on newer Claude models and a code-execution tool on Celigo AI. Preview the agent on one record before wiring it into a flow.

Common Errors