Ctrlk
For the complete documentation index, see llms.txt. This page is also available as Markdown.

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

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

Supports all global flags.

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

Example

Corresponds to: GET /v1/imports (filtered to adaptorType=AiAgentImport) → Imports API reference.

celigo ai-agents get

Fetch a single AI agent by ID.

Signature

Arguments

Argument
Type
Required
Description

<id>

string

Yes

AI agent import _id.

Example

Corresponds to: 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

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

Corresponds to: 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

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

Corresponds to: 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

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

Corresponds to: GET /v1/imports/{_id} then 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

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

Corresponds to: 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

Arguments

Argument
Type
Required
Description

[id]

string

No

AI agent import _id. Omit to preview a piped agent document.

Examples

Corresponds to: 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

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

Corresponds to: 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

Arguments

Argument
Type
Required
Description

<id>

string

Yes

AI agent import _id.

Example

Corresponds to: 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

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

Corresponds to: 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

Arguments

Argument
Type
Required
Description

<id>

string

Yes

AI agent import _id.

<newConnectionId>

string

Yes

Connection _id to attach.

Example

Corresponds to: 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 — AI safety imports (PII, moderation, AI evaluation) with the same command surface.

  • tools — reusable building blocks that agents can call as tools.

  • mcp-servers — expose agents and tools to external MCP clients.

  • imports — the underlying resource type; general-purpose import commands.

  • connections — BYOK and provider-key connections referenced by agents.

Previousaccount
Nextapis

Last updated

Was this helpful?