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

**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 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 JSON on stdin (`adaptorType` auto-set).                               |
| `update <id>`                               | Full replace from stdin (destructive `PUT`).                                               |
| `set <id> key=value …`                      | Safe field edit via 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. |
| `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).                                            |

***

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

**Example**

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

**Corresponds to**: [`GET /v1/imports`](https://developer.celigo.com/api/api-reference/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/imports#get-v1-imports-_id) → Imports API reference.

***

## `celigo ai-agents create`

Create an AI agent from JSON piped via stdin. The CLI force-sets `adaptorType: AiAgentImport` before `POST`.

**Signature**

```bash
celigo ai-agents create
```

**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/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.

**Signature**

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

**Arguments**

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

**Request body**

Reads JSON on stdin. 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/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. Values are auto-parsed (`disabled=false` → boolean). Dot notation is supported for nested fields.

**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/imports#get-v1-imports-_id) then [`PUT /v1/imports/{_id}`](https://developer.celigo.com/api/api-reference/imports#put-v1-imports-_id) → Imports API reference.

***

## `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/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. Two modes:

* **With `<id>`** — invoke a *saved* agent; pipe input records on stdin (`POST /v1/imports/{_id}/invoke`).
* **Without `<id>`** — pipe an *agent document* on stdin to preview its output without saving (`POST /v1/imports/preview`; the CLI sets `adaptorType: AiAgentImport`). Stdin is required in this mode.

**Signature**

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

**Arguments**

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

**Examples**

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

# Preview an unsaved agent document
celigo ai-agents invoke < agent.json
```

**Corresponds to**: [`POST /v1/imports/{_id}/invoke`](https://developer.celigo.com/api/api-reference/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.

**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`. |

**Example**

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

**Corresponds to**: [`PATCH /v1/imports/{_id}`](https://developer.celigo.com/api/api-reference/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.

**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/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.

**Signature**

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

**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). |

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

Reads JSON on stdin: `{"connectionMap":{"<sourceConnId>":"<targetConnId>"},"name":"..."}`. If omitted, the CLI builds `{ [_connectionId]: _connectionId }` from the source.

**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/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.

**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/imports#put-v1-imports-_id-replaceconnection) → Imports 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`.** Don't fight the CLI by setting a different value in your stdin payload; `ai-agents create` overwrites it to `AiAgentImport`.
* **Per-ID ops are type-guarded.** `get`, `update`, `set`, `delete`, `clone`, and `invoke <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). The id-less preview form of `invoke` instead sets `adaptorType` on the piped document.
* **Debug window caps at 60 minutes.** `--duration` values above 60 are silently clamped. Re-run `enable-debug` to extend.
* **Debug requires inspecting via `imports`.** Agents are imports under the hood, so debug captures and test-run logs surface through the `imports` endpoints, not a dedicated `ai-agents` tree.
* **`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.
* [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 dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter, and the optional `goal` query parameter:

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

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is optional and describes the broader end goal you are ultimately trying to accomplish on behalf of the user. GitBook uses it to tailor the answer towards what is most useful for that goal.

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.