> For the complete documentation index, see [llms.txt](https://developer.celigo.com/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://developer.celigo.com/cli/commands/ai-agents.md).

# ai-agents

Manage AI agent imports — LLM-powered flow steps (classify, extract, validate, generate) that run OpenAI, Gemini, or BYOK-compatible models inline. The `guardrails` CLI (AI safety checks) is documented separately.

Two commands try an agent. `invoke` runs the step against records. `chat` sends the agent one message — the saved agent, or an unsaved document to try a change before you save it — and prints the reply, the tools the agent ran, and the turn's cost. Both are real, billed runs whose tools act for real.

`model-health` lists the AI agents and guardrails whose model is refused (blocked on save and on run) or deprecated (working until its retirement date), with the models the platform suggests instead. `--integration` narrows the list to one integration's live flows.

**REST API**: AI agents are a specialized import (`adaptorType: AiAgentImport`) stored under `/v1/imports`. Schemas live in the imports spec — see the `AiAgentImport` components. The CLI filters and auto-tags so you don't need to pass the adaptor type yourself. The routes behind `chat` and `model-health` are documented in the [AI Agents](https://developer.celigo.com/api/api-reference/ai-and-mcp/ai-agents) API reference. (The separate `agent.yml` spec covers on-premise agents, documented at [on-premise-agents](/cli/commands/on-premise-agents.md).)

```
celigo ai-agents <subcommand> [args] [flags]
```

Supports all [global flags](/cli/getting-started/global-flags.md).

***

## Subcommands

| Subcommand                                  | Purpose                                                                                                                                                                         |
| ------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `list`                                      | List all AI agent imports.                                                                                                                                                      |
| `get <id>`                                  | Fetch one agent by ID.                                                                                                                                                          |
| `create`                                    | Create an agent from a JSON body (`--file <path>` or stdin; `adaptorType` auto-set).                                                                                            |
| `update <id>`                               | Full replace from a JSON body (`--file <path>` or stdin); destructive `PUT`.                                                                                                    |
| `set <id> key=value …`                      | Safe field edit: `debugUntil` as one atomic PATCH, any other field through GET → modify → PUT.                                                                                  |
| `delete <id>`                               | Delete an agent.                                                                                                                                                                |
| `invoke [id]`                               | Invoke a saved agent with input records, or preview a piped agent doc when no id is given. Either form is a real, billed run.                                                   |
| `enable-debug <id>`                         | Enable debug logging (sets `debugUntil`).                                                                                                                                       |
| `disable-debug <id>`                        | Disable debug logging.                                                                                                                                                          |
| `clone <id>`                                | Clone an agent.                                                                                                                                                                 |
| `replace-connection <id> <newConnectionId>` | Swap the underlying connection (e.g. BYOK key).                                                                                                                                 |
| `chat [id]`                                 | Send a saved agent, or an unsaved agent document, one message and print the turn: the reply, the tools it ran, and the cost. A real, billed run. Added in celigo-cli 2026.10.2. |
| `model-health`                              | List the AI agents and guardrails on a refused or deprecated model, with the models the platform suggests instead. Added in celigo-cli 2026.10.2.                               |

***

## `celigo ai-agents list`

List every AI agent import on the account. Behind the scenes, lists `/v1/imports` and filters by `adaptorType = AiAgentImport`.

**Signature**

```bash
celigo ai-agents list [--fields <spec>]
```

**Flags**

| Flag              | Type   | Default   | Description                                                                                                                                                                                                                                                                                                                            |
| ----------------- | ------ | --------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `--fields <spec>` | string | `default` | Fields to request per row: `default` (`_id`, `name`, and the table columns), `all` (complete documents), or a comma-separated field list (dot notation allowed). `adaptorType` is always requested too, because the CLI filters on it. See [field projection](/cli/getting-started/global-flags.md#field-projection-on-list-commands). |

Table columns: `_id`, `name`, `lastModified`. There is no `--limit`: the filter runs client-side over every import.

**Example**

```bash
celigo ai-agents list --format table
```

**Corresponds to**: [`GET /v1/imports`](https://developer.celigo.com/api/api-reference/exports-imports-and-tools/imports#get-v1-imports) (filtered to `adaptorType=AiAgentImport`) → Imports API reference.

***

## `celigo ai-agents get`

Fetch a single AI agent by ID.

**Signature**

```bash
celigo ai-agents get <id>
```

**Arguments**

| Argument | Type   | Required | Description            |
| -------- | ------ | -------- | ---------------------- |
| `<id>`   | string | Yes      | AI agent import `_id`. |

**Example**

```bash
celigo ai-agents get 64f1a2b3c4d5e6f7a8b9c0d1
```

**Corresponds to**: [`GET /v1/imports/{_id}`](https://developer.celigo.com/api/api-reference/exports-imports-and-tools/imports#get-v1-imports-_id) → Imports API reference.

***

## `celigo ai-agents create`

Create an AI agent from a JSON body — read from a file with `-f, --file`, or piped on stdin. The CLI sets `adaptorType: AiAgentImport` before the `POST`. Since celigo-cli 2026.10.1, a body whose `adaptorType` names another import type is refused instead of overwritten:

```
Refusing to create an ai-agent: the body's adaptorType is HTTPImport, not AiAgentImport — this group never changes an import's type; `celigo imports` writes other import types.
```

Since celigo-cli 2026.10.1, the body is also checked as `imports create` checks one: a body that is not a JSON object, masked `"******"` credential placeholders, and a `responseMapping` object wrapper are refused before any request, with no override, and the body is validated against the published API schemas — findings print as `warning` lines on stderr and never block.

**Signature**

```bash
celigo ai-agents create --file <path>
celigo ai-agents create < agent.json     # or pipe on stdin
```

**Flags**

| Flag                | Type   | Default | Description                                                                    |
| ------------------- | ------ | ------- | ------------------------------------------------------------------------------ |
| `-f, --file <path>` | string | —       | Read the JSON body from a file instead of stdin (`--file -` also means stdin). |

**Request body**

Reads JSON on stdin. See the `POST /v1/imports` request schema for the full `AiAgentImport` payload (including the `aiAgent` block: `provider`, `model`, `prompt`, `outputSchema`, `tools`).

**Example**

```bash
celigo ai-agents create < agent.json
```

**Corresponds to**: [`POST /v1/imports`](https://developer.celigo.com/api/api-reference/exports-imports-and-tools/imports#post-v1-imports) → Imports API reference.

***

## `celigo ai-agents update`

Full replace of an AI agent document.

> ⚠️ **`update` erases omitted fields.** It sends a `PUT`, not a `PATCH`, so any field missing from the stdin document is cleared. `GET` the agent first, modify it, then pipe back the complete document — or use `set` for targeted edits.

Since celigo-cli 2026.10.1, `update` runs the checks `imports update` runs, after its read of the agent (which refuses an import of another type): a body that is not a JSON object, a body whose `adaptorType` names another import type, masked `"******"` credential placeholders (unless `--force`), and a `responseMapping` object wrapper or `null` are refused before the PUT. The body is checked against the published API schemas, with the copy just read as evidence, and findings are stderr warnings that never block. On an Integration App's agent (`_connectorId` set), each field the update changed whose reply still holds the previous value is named on stderr, and the command exits `1`.

**Signature**

```bash
celigo ai-agents update <id> --file <path>
celigo ai-agents update <id> < agent.json     # or pipe on stdin
```

**Arguments**

| Argument | Type   | Required | Description            |
| -------- | ------ | -------- | ---------------------- |
| `<id>`   | string | Yes      | AI agent import `_id`. |

**Flags**

| Flag                | Type    | Default | Description                                                                                                                                                       |
| ------------------- | ------- | ------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `-f, --file <path>` | string  | —       | Read the JSON body from a file instead of stdin (`--file -` also means stdin).                                                                                    |
| `--force`           | boolean | `false` | Submit even if the body contains masked credential values (`"******"`, four or more asterisks and nothing else) copied from a GET. Added in celigo-cli 2026.10.1. |

**Request body**

Reads JSON on stdin, or from `--file`. Must contain the complete agent document. See the `PUT /v1/imports/{_id}` request schema.

**Example**

```bash
celigo ai-agents get 64f1a2b3c4d5e6f7a8b9c0d1 --format json \
  | jq '.aiAgent.model = "gpt-4o"' \
  | celigo ai-agents update 64f1a2b3c4d5e6f7a8b9c0d1
```

**Corresponds to**: [`PUT /v1/imports/{_id}`](https://developer.celigo.com/api/api-reference/exports-imports-and-tools/imports#put-v1-imports-_id) → Imports API reference.

***

## `celigo ai-agents set`

Safely edit one or more fields on an agent. The CLI does `GET → modify → PUT` so unrelated fields are preserved — except `debugUntil` alone, which since celigo-cli 2026.10.1 goes as one atomic PATCH on the field, as `imports set` sends it. Values are auto-parsed (`disabled=false` → boolean, `debugUntil=null` → removes the field). Dot notation is supported for nested fields.

Since celigo-cli 2026.10.1, `set` holds the rules `imports set` holds:

* In `operate` mode it takes only `debugUntil`; any other field needs `full` mode. See [permission modes](/cli/getting-started/profiles.md#permission-modes).
* An assignment that would change the import's type — another `adaptorType`, or `adaptorType=null` — is refused.
* A GET + PUT is refused when the agent the server returned carries a masked `"******"` value, which the PUT would write back over the secret; use `update` with the real value.
* The assigned values (PATCH) or the document it would PUT are checked against the published API schemas, as stderr warnings that never block, and a `responseMapping` object wrapper or `null` is refused.
* After a GET + PUT, a field the server's reply still holds at its previous value prints `not stored <field> the server answered the PUT but still holds its previous value …` on stderr, and the command exits `1`; on an Integration App's agent, one line names the fields the app kept instead.

**Signature**

```bash
celigo ai-agents set <id> <assignment> [assignment ...]
```

**Arguments**

| Argument       | Type        | Required          | Description                                               |
| -------------- | ----------- | ----------------- | --------------------------------------------------------- |
| `<id>`         | string      | Yes               | AI agent import `_id`.                                    |
| `<assignment>` | `key=value` | Yes (one or more) | Field path and new value. Dot notation for nested fields. |

**Example**

```bash
celigo ai-agents set 64f1a2b3c4d5e6f7a8b9c0d1 \
  name="Classify tickets (v2)" \
  aiAgent.model=gpt-4o \
  disabled=false
```

**Corresponds to**: [`GET /v1/imports/{_id}`](https://developer.celigo.com/api/api-reference/exports-imports-and-tools/imports#get-v1-imports-_id) then [`PUT /v1/imports/{_id}`](https://developer.celigo.com/api/api-reference/exports-imports-and-tools/imports#put-v1-imports-_id) → Imports API reference; for `debugUntil` alone, the GET then [`PATCH /v1/imports/{_id}`](https://developer.celigo.com/api/api-reference/exports-imports-and-tools/imports).

***

## `celigo ai-agents delete`

Delete an AI agent by ID. Prompts for confirmation unless `-y` is passed.

> ⚠️ **`delete` is immediate.** Any flow step that references this agent fails until you remove or repoint it.

**Signature**

```bash
celigo ai-agents delete <id> [-y]
```

**Arguments**

| Argument | Type   | Required | Description            |
| -------- | ------ | -------- | ---------------------- |
| `<id>`   | string | Yes      | AI agent import `_id`. |

**Flags**

| Flag          | Type    | Default | Description                   |
| ------------- | ------- | ------- | ----------------------------- |
| `-y`, `--yes` | boolean | `false` | Skip the confirmation prompt. |

**Example**

```bash
celigo ai-agents delete 64f1a2b3c4d5e6f7a8b9c0d1 -y
```

**Corresponds to**: [`DELETE /v1/imports/{_id}`](https://developer.celigo.com/api/api-reference/exports-imports-and-tools/imports#delete-v1-imports-_id) → Imports API reference.

***

## `celigo ai-agents invoke [id]`

Run an AI agent without creating a job — useful for prompt iteration and testing. To send the agent one message instead of records, use [`chat`](#celigo-ai-agents-chat-id).

> ⚠️ **`invoke` is a real, billed run, not a dry run.** In either form, the model is called, and the agent's tools (MCP servers, Celigo Tools, web search) act for real.

Two modes:

* **With `<id>`** — invoke a *saved* agent; pipe input records on stdin, or pass them with `--file` (`POST /v1/imports/{_id}/invoke`). The API answers HTTP 200 whatever happened to each record, so check each result's `statusCode` and `errors`. Since celigo-cli 2026.10.1, a count prints on stderr, and since celigo-cli 2026.10.2 it counts each record by cause — `2 record(s): 1 accepted, 1 rejected by the destination, 0 failed before sending, 0 failed after sending (the destination may already hold them), 0 ignored and never sent.` (see [`imports invoke`](/cli/commands/imports.md#celigo-imports-invoke-id) for what each cause means). The records are optional in this mode; since celigo-cli 2026.10.1, a body piped without `--file` gets one second to start arriving and is then read to its end (use `--file -` behind a slower producer).
* **Without `<id>`** — preview an *agent document* without saving (`POST /v1/imports/preview`): pipe `{"import": <agent document>, "data": [records]}`, or the bare document to preview it with one empty record. The CLI sets `adaptorType: AiAgentImport` on the document. Input is required in this mode. Since celigo-cli 2026.10.1, the CLI sends the `{import, data}` envelope the endpoint requires, and refuses before any request a body that is not a JSON object, an envelope whose `import` is not a document or whose `data` is not an array, and a document of another import type (`celigo imports invoke` previews those).

Since celigo-cli 2026.11.1, in either mode, a credential the result carries prints as `********`: the value of each credential header, and a captured request URL's userinfo and credential query parameters. See [Credentials in a run's result](/cli/using-the-cli/output-formats.md#credentials-in-a-runs-result).

**Signature**

```bash
celigo ai-agents invoke [id] [-f <path>]
```

**Arguments**

| Argument | Type   | Required | Description                                                    |
| -------- | ------ | -------- | -------------------------------------------------------------- |
| `[id]`   | string | No       | AI agent import `_id`. Omit to preview a piped agent document. |

**Flags**

| Flag                | Type   | Default | Description                                                                                                            |
| ------------------- | ------ | ------- | ---------------------------------------------------------------------------------------------------------------------- |
| `-f, --file <path>` | string | stdin   | Read the records or the agent document from a file instead of stdin (`-` also means stdin, and waits for it to close). |

**Request body**

| Form           | Body                                                                                                                   |
| -------------- | ---------------------------------------------------------------------------------------------------------------------- |
| With `<id>`    | The input records: `[{...}, ...]`. Optional.                                                                           |
| Without `<id>` | `{"import": <agent document>, "data": [{...}, ...]}`, or the bare agent document (previewed against one empty record). |

**Examples**

```bash
# Invoke a saved agent with input records (the count prints on stderr)
echo '[{"subject":"Billing issue","body":"My invoice is wrong"}]' \
  | celigo ai-agents invoke 64f1a2b3c4d5e6f7a8b9c0d1

# Preview an unsaved agent document against two records
celigo ai-agents invoke --file preview.json    # {"import": {...}, "data": [{...}, {...}]}

# Preview the bare document against one empty record
celigo ai-agents invoke < agent.json
```

**Corresponds to**: [`POST /v1/imports/{_id}/invoke`](https://developer.celigo.com/api/api-reference/exports-imports-and-tools/imports#post-v1-imports-_id-invoke) (with `id`) or `POST /v1/imports/preview` (without).

***

## `celigo ai-agents enable-debug`

Turn on debug logging for an agent by setting `debugUntil` to a future timestamp via `PATCH`. Debug runs capture the full prompt, model response, and tool calls; fetch the captures from the flow, API, or tool that runs the agent, with `flows debug-requests <flowId> <agentId>` (or `apis`/`tools debug-requests`). Requires `operate` mode.

Since celigo-cli 2026.10.1, the import is read first and one of another type is refused before the `PATCH`:

```
Import 5f8d43a1b9e5a80011a35f2c is not an ai-agent (adaptorType=HTTPImport). Use `celigo imports` for non-ai-agent imports.
```

**Signature**

```bash
celigo ai-agents enable-debug <id> [--duration <minutes>]
```

**Arguments**

| Argument | Type   | Required | Description            |
| -------- | ------ | -------- | ---------------------- |
| `<id>`   | string | Yes      | AI agent import `_id`. |

**Flags**

| Flag                   | Type    | Default | Description                                                                                                                                                                     |
| ---------------------- | ------- | ------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `--duration <minutes>` | integer | `60`    | Debug window in minutes. Capped at `60`. Since celigo-cli 2026.10.1, a value that is not a positive whole number is refused instead of setting a window that has already ended. |

**Example**

```bash
celigo ai-agents enable-debug 64f1a2b3c4d5e6f7a8b9c0d1 --duration 30
```

**Corresponds to**: [`PATCH /v1/imports/{_id}`](https://developer.celigo.com/api/api-reference/exports-imports-and-tools/imports#patch-v1-imports-_id) with `[{"op":"replace","path":"/debugUntil","value":"<iso>"}]` → Imports API reference.

***

## `celigo ai-agents disable-debug`

Clear `debugUntil` on an agent via `PATCH`, immediately stopping debug capture. Requires `operate` mode. Since celigo-cli 2026.10.1, the import is read first and one of another type is refused, as `enable-debug` refuses it.

**Signature**

```bash
celigo ai-agents disable-debug <id>
```

**Arguments**

| Argument | Type   | Required | Description            |
| -------- | ------ | -------- | ---------------------- |
| `<id>`   | string | Yes      | AI agent import `_id`. |

**Example**

```bash
celigo ai-agents disable-debug 64f1a2b3c4d5e6f7a8b9c0d1
```

**Corresponds to**: [`PATCH /v1/imports/{_id}`](https://developer.celigo.com/api/api-reference/exports-imports-and-tools/imports#patch-v1-imports-_id) with `[{"op":"remove","path":"/debugUntil"}]` → Imports API reference.

***

## `celigo ai-agents clone`

Clone an AI agent. Same-env clones auto-build a self-map from the source agent's connection (no stdin needed). Cross-env clones accept a connection map on stdin or in `--file`.

**Signature**

```bash
celigo ai-agents clone <id> [--name <name>] [-f <path>]
```

**Arguments**

| Argument | Type   | Required | Description            |
| -------- | ------ | -------- | ---------------------- |
| `<id>`   | string | Yes      | Source AI agent `_id`. |

**Flags**

| Flag                | Type   | Default                 | Description                                                                                                                     |
| ------------------- | ------ | ----------------------- | ------------------------------------------------------------------------------------------------------------------------------- |
| `--name <name>`     | string | `Clone - <source name>` | Name for the cloned agent (matches the UI default).                                                                             |
| `-f, --file <path>` | string | —                       | Read the `connectionMap` body from a file instead of stdin. `--file -` waits until stdin closes. Added in celigo-cli 2026.10.1. |

**Request body** (optional, cross-env only)

Reads JSON on stdin, or from `--file`: `{"connectionMap":{"<sourceConnId>":"<targetConnId>"}}`. The clone's name comes from `--name`. If the body is omitted, the CLI builds `{ [_connectionId]: _connectionId }` from the source. Since celigo-cli 2026.10.1, a body piped without `--file` must start arriving within one second and is then read to its end; behind a slower producer, use `--file -`. A body that is not a JSON object is refused before any request.

**Example**

```bash
# Same-env clone
celigo ai-agents clone 64f1a2b3c4d5e6f7a8b9c0d1 --name "Classify tickets (staging)"

# Cross-env clone
echo '{"connectionMap":{"srcConn":"tgtConn"}}' \
  | celigo ai-agents clone 64f1a2b3c4d5e6f7a8b9c0d1
```

**Corresponds to**: [`POST /v1/imports/{_id}/clone`](https://developer.celigo.com/api/api-reference/exports-imports-and-tools/imports#post-v1-imports-_id-clone) → Imports API reference.

***

## `celigo ai-agents replace-connection`

Swap the connection referenced by an agent (e.g. rotate a BYOK API key connection) without rewriting the full document. Since celigo-cli 2026.10.1, the import is read first and one of another type is refused before the swap.

**Signature**

```bash
celigo ai-agents replace-connection <id> <newConnectionId>
```

**Arguments**

| Argument            | Type   | Required | Description                 |
| ------------------- | ------ | -------- | --------------------------- |
| `<id>`              | string | Yes      | AI agent import `_id`.      |
| `<newConnectionId>` | string | Yes      | Connection `_id` to attach. |

**Example**

```bash
celigo ai-agents replace-connection 64f1a2b3c4d5e6f7a8b9c0d1 64f9a1b2c3d4e5f6a7b8c9d0
```

**Corresponds to**: [`PUT /v1/imports/{_id}/replaceConnection`](https://developer.celigo.com/api/api-reference/exports-imports-and-tools/imports#put-v1-imports-_id-replaceconnection) → Imports API reference.

***

## `celigo ai-agents chat [id]`

Send an AI agent one message and print the turn: the reply, the tools the agent ran, the files it produced, token usage and AI-credit cost, and whether the turn succeeded. Added in celigo-cli 2026.10.2.

> ⚠️ **Every turn is a real, billed run, not a dry run.** The model is called — AI credits on a hosted model, the key owner's account on a BYOK one — and the agent's tools (MCP servers, Celigo Tools, web search) act for real.

Two modes:

* **With `<id>`** — the saved agent answers (`POST /v1/imports/{_id}/aiagents/chat`). The CLI reads the import first and refuses one that is not an AI agent, as every per-id command here does. `--file` is refused in this mode.
* **Without `<id>`** — an unsaved agent document answers (`POST /v1/aiagents/chat`). Pipe it on stdin or pass it with `--file`, as `ai-agents get` prints it, edited or not. The document is never saved, so this is how you try a change before you save it. The CLI sets `adaptorType: AiAgentImport` on the document. It refuses an `{"import": …}` envelope (the message travels in `--message`) and a document of another import type, before any request.

`--conversation <key>` keeps a conversation across turns: turns sent with the same key share a history. The key is yours to choose, at most 200 characters, and scoped to you and the agent. Without it, the turn stands alone and nothing is stored.

None of the flow pipeline runs: no input filter, mappings, hooks, or response mapping. To run the step against records, use [`invoke`](#celigo-ai-agents-invoke-id).

`chat` needs `operate` mode, like `invoke`, and the manage or administrator role; a monitor user gets `403`. A request that timed out or failed with a `5xx` or a `429` is not resent (the `429` since celigo-cli 2026.11.1; earlier releases retried it).

**Signature**

```bash
celigo ai-agents chat <id> --message <text> [--conversation <key>] [--events]
celigo ai-agents chat --message <text> --file <path> [--conversation <key>] [--events]
celigo ai-agents chat --message <text> < agent.json     # or pipe the document on stdin
```

**Arguments**

| Argument | Type   | Required | Description                                                                                   |
| -------- | ------ | -------- | --------------------------------------------------------------------------------------------- |
| `[id]`   | string | No       | AI agent import `_id`. Omit it to chat with an unsaved agent document from stdin or `--file`. |

**Flags**

| Flag                   | Type    | Default | Description                                                                                                                                           |
| ---------------------- | ------- | ------- | ----------------------------------------------------------------------------------------------------------------------------------------------------- |
| `--message <text>`     | string  | —       | Required. The message the agent answers.                                                                                                              |
| `--conversation <key>` | string  | —       | Keep a conversation: turns sent with the same key share a history. At most 200 characters; a blank key or a longer one is refused before any request. |
| `-f, --file <path>`    | string  | stdin   | Without `<id>`: read the unsaved agent document from a file instead of stdin (`-` also means stdin). Refused beside an `<id>`.                        |
| `--events`             | boolean | `false` | Also print every event the turn streamed, in order, under `events`.                                                                                   |

A `--message` that is empty or only whitespace is refused before any request:

```
--message has no visible text: the agent answers a message, and whitespace alone counts as empty.
```

**Request body**

The CLI builds the body from the flags. With an `<id>`, nothing is read from stdin.

| Form           | Body                                                                                                                        |
| -------------- | --------------------------------------------------------------------------------------------------------------------------- |
| With `<id>`    | `{"data": [{"text": "<message>", "conversationHistoryId": "<key>"}]}` — `conversationHistoryId` only with `--conversation`. |
| Without `<id>` | The same, plus `"import": <agent document>`.                                                                                |

**Output**

The CLI reads the whole event stream, then prints the turn as one object:

| Key         | Description                                                                     |
| ----------- | ------------------------------------------------------------------------------- |
| `requestId` | The turn's request id.                                                          |
| `reply`     | The agent's reply, joined from the streamed chunks.                             |
| `success`   | `true` when the turn completed with no error event.                             |
| `usage`     | Token usage and AI-credit cost, as the stream reported them.                    |
| `tools`     | The tools the agent ran. Present only when it ran any.                          |
| `files`     | Signed URLs of the files the agent produced. Present only when it produced any. |
| `errors`    | The error events the stream carried. Present only when there were any.          |
| `events`    | With `--events`: every event the turn streamed, in order, as `{event, data}`.   |

A turn the agent could not finish still answers HTTP 200, with the error inside the stream. The command prints the turn with `success: false`, names the failure on stderr, and exits `1`:

```
celigo: ai-agents chat: the turn failed: <code>: <message>
```

The failure can also read `the stream ended before the turn completed` or `the agent ended the turn unsuccessfully`. An answer that is not an event stream is printed as it came, with a note on stderr, and the command exits `1`.

**Examples**

```bash
# Send a saved agent one message
celigo ai-agents chat 64f1a2b3c4d5e6f7a8b9c0d1 \
  --message "Classify this ticket: the invoice total is wrong on order 4411."

# Keep a conversation across two turns, and print only the replies
celigo ai-agents chat 64f1a2b3c4d5e6f7a8b9c0d1 --conversation ticket-4411 \
  --message "Classify this ticket: the invoice total is wrong on order 4411." --jq .reply
celigo ai-agents chat 64f1a2b3c4d5e6f7a8b9c0d1 --conversation ticket-4411 \
  --message "Which team handles it?" --jq .reply

# Try an edited document before you save it
celigo ai-agents get 64f1a2b3c4d5e6f7a8b9c0d1 --format json > agent.json
# ...edit agent.json, then:
celigo ai-agents chat --file agent.json \
  --message "Classify this ticket: the invoice total is wrong on order 4411."
```

**Corresponds to**: [`POST /v1/imports/{_id}/aiagents/chat`](https://developer.celigo.com/api/api-reference/ai-and-mcp/ai-agents#post-v1-imports-_id-aiagents-chat) (with `id`, after the type check's [`GET /v1/imports/{_id}`](https://developer.celigo.com/api/api-reference/exports-imports-and-tools/imports#get-v1-imports-_id)) or [`POST /v1/aiagents/chat`](https://developer.celigo.com/api/api-reference/ai-and-mcp/ai-agents#post-v1-aiagents-chat) (without) → AI Agents API reference.

***

## `celigo ai-agents model-health`

List the AI agents and guardrails on an affected model, with the models the platform suggests instead. `model-health` only reads, so it works in `read` mode. Added in celigo-cli 2026.10.2.

An affected model is one of two kinds:

* **Refused** (`severity: error`) — the catalog refuses the model, so the import is blocked on save and on run. `code` says why.
* **Deprecated** (`severity: warning`) — the model keeps working until `lifecycle.retiredAt`.

Change such an import's model, usually to one of `lifecycle.suggestedNextModels`. Healthy imports are left out, so an empty `agents` list means every model is fine. The report is computed on every call.

With `--integration <id>`, the list keeps only the imports that a live flow of that integration uses, each with the `_flowIds` and `_integrationIds` that use it. A parent Integration App includes its children's flows.

**Signature**

```bash
celigo ai-agents model-health [--integration <id>]
```

**Flags**

| Flag                 | Type   | Default | Description                                                                                                 |
| -------------------- | ------ | ------- | ----------------------------------------------------------------------------------------------------------- |
| `--integration <id>` | string | —       | Only the imports this integration's live flows use. A parent Integration App includes its children's flows. |

**Output**

JSON output is the API's envelope, `{"agents": [...]}`, with one entry per affected import. `--format table` lists one import per row: `_importId`, `modelId`, `provider`, `severity`, `code`, `lifecycle.retiredAt`, and `lifecycle.suggestedNextModels`, plus `_flowIds` with `--integration`.

**Examples**

```bash
# Every AI agent and guardrail on a refused or deprecated model
celigo ai-agents model-health --format table

# The imports one integration's live flows use, with the flows that use each
celigo ai-agents model-health --integration 5f83a9b2c7d3e8f1a2b3c4d5 --format table

# Only the refused models, which block save and run
celigo ai-agents model-health --jq '[.agents[] | select(.severity == "error")]'
```

**Corresponds to**: [`GET /v1/aiagents/aiModelHealth`](https://developer.celigo.com/api/api-reference/ai-and-mcp/ai-agents#get-v1-aiagents-aimodelhealth), or [`GET /v1/integrations/{_integrationId}/aiModelHealth`](https://developer.celigo.com/api/api-reference/ai-and-mcp/ai-agents#get-v1-integrations-_integrationid-aimodelhealth) with `--integration` → AI Agents API reference.

***

## Gotchas

* **Providers.** AI agents currently support three providers: **OpenAI** (GPT-4 / 4o family via API key), **Gemini** (Google 1.5 / 2.0 via API key), and **BYOK** — bring-your-own-key against any OpenAI-compatible endpoint. The provider lives at `aiAgent.provider`; see the schema for per-provider fields.
* **BYOK requires a connection.** OpenAI and Gemini agents can reference a shared platform key, but BYOK agents must point at a connection you own. Use `replace-connection` when rotating the key rather than editing the document.
* **Prompt schema.** The `aiAgent.prompt` block expects a structured prompt (system / user / optional tools). Freeform strings won't validate — see the `aiAgent` schema in the Imports spec for required fields and Handlebars placeholders (e.g. `{{{record.fieldName}}}`).
* **`adaptorType` is auto-set by `create`.** Leave it out of the body: `ai-agents create` sets it to `AiAgentImport`. Since celigo-cli 2026.10.1, a body or assignment naming another import type — or `adaptorType=null` — is refused by `create`, `update`, and `set` instead of being overwritten; `celigo imports` writes other import types.
* **Per-ID ops are type-guarded.** `get`, `update`, `set`, `delete`, `clone`, `invoke <id>`, and `chat <id>` first fetch the target and verify `adaptorType = AiAgentImport`; a non-agent import ID is rejected with a clear error (the server's `/v1/imports/{id}` is not scoped by type, so the CLI enforces the boundary). Since celigo-cli 2026.10.1, `enable-debug`, `disable-debug`, and `replace-connection` do the same; they used to write to whatever import the id named. The id-less forms of `invoke` and `chat` instead set `adaptorType` on the piped document, and refuse one of another type.
* **Debug window caps at 60 minutes.** `--duration` values above 60 are silently clamped. Re-run `enable-debug` to extend.
* **Debug captures are read from the consumer.** Agents are imports under the hood: with `debugUntil` set, the captures are listed by `flows debug-requests <flowId> <agentId>` (or `apis`/`tools debug-requests`) for the flow, API, or tool that runs the agent, not by a dedicated `ai-agents` command.
* **`chat` runs the agent, not the step.** None of the flow pipeline runs — no input filter, mappings, hooks, or response mapping — yet the turn is still a real, billed run whose tools act for real. Use `invoke` to run the step against records.
* **`create`, `clone`, `invoke`, and `chat` are sent once.** Since celigo-cli 2026.10.1, a timeout or a 5xx on `create`, `clone`, or `invoke` is reported and never retried, and `chat` works the same way. Since celigo-cli 2026.11.1 a `429` is not retried on any of them either; earlier releases retried it. The request may have reached the server, so check for the result before you run the command again.
* **Permission modes.** `list`, `get`, and `model-health` work in `read` mode. `invoke` and `chat` (with or without an id), `enable-debug`, `disable-debug`, and `set <id> debugUntil=…` need `operate`. `create`, `update`, `delete`, `clone`, `replace-connection`, and any other `set` need `full`. Since celigo-cli 2026.10.1, `read` mode refuses the `operate` verbs before any request, and `operate` mode's `set` takes only `debugUntil`. See [Profiles & regions](/cli/getting-started/profiles.md#permission-modes).
* **`update` is destructive.** It's `PUT`, not `PATCH`. Always `GET` → modify → `PUT` a complete document, or use `set` for targeted edits.

## Related

* [guardrails](/cli/commands/guardrails.md) — AI safety imports (PII, moderation, AI evaluation) with the same command surface, apart from `chat` and `model-health`. `model-health` lists the guardrails on an affected model too.
* [tools](/cli/commands/tools.md) — reusable building blocks that agents can call as tools.
* [mcp-servers](/cli/commands/mcp-servers.md) — expose agents and tools to external MCP clients.
* [imports](/cli/commands/imports.md) — the underlying resource type; general-purpose import commands.
* [connections](/cli/commands/connections.md) — BYOK and provider-key connections referenced by agents.


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation by asking a question.

Perform an HTTP GET request on the following URL with the `ask` and `goal` query parameters:

```
GET https://developer.celigo.com/cli/commands/ai-agents.md?ask=<question>&goal=<user_goal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is what the user is ultimately trying to achieve, the reason they need the answer. Sharing it helps GitBook give you a better, more relevant answer. A goal is most helpful when it describes the outcome the user wants rather than restating the question. For example, with `ask=how do I create an API token`, a goal like `automate deployments from our CI pipeline` lets GitBook tailor the answer to that use case.

The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.