atlanai agent

Agent commands manage autonomous agent definitions. Agents are separate from human-driven harness artifacts.

Commands

list

Lists agents visible to the authenticated identity. Usage

atlanai agent list [flags]

Option	Type	Default	Description
`--framework`	string	none	Restrict results to one agent framework ID.
`--provider`	string	none	Restrict results to one agent provider ID.
`--model`	string	none	Restrict results to one model ID.
`--limit`, `-L`	integer	server default	Maximum results, up to `500`.
`--offset`	integer	`0`	Results to skip, up to `10000`.
`--sort`	string	server default	Comma-separated fields; prefix descending fields with `-`.
`--json`, `--jq`, `--template`	output controls	human table	Select and format structured output.

search

Searches every accessible workspace unless --workspace narrows the request. Usage

atlanai agent search <query> [flags]

Option	Type	Default	Description
`--strategy`	enum	`hybrid`	Search with `fts`, `vector`, or `hybrid`.
`--workspace`, `-w`	string	all accessible workspaces	Restrict discovery to one workspace ID.
`--limit`, `-L`	integer	server default	Maximum results, up to `500`.
`--offset`	integer	`0`	Results to skip, up to `10000`.
`--json`, `--jq`, `--template`	output controls	human table	Select and format structured output.

get

Shows one agent by its stable agent_... ID. Usage

atlanai agent get <agent-id> [--json <fields>] [--jq <expression>] [--template <template>]

validate

Validates one local YAML or JSON agent definition without writing to the Registry. Usage

atlanai agent validate <agent.yaml>

create

Creates an agent from a local YAML or JSON definition. Usage

atlanai agent create --file <agent.yaml> [flags]

Option	Type	Default	Description
`--file`, `-f`	path	required	Agent YAML or JSON definition.
`--workspace`, `-w`	string	active context	Workspace in which to create the agent.
`--dry-run`	Boolean	`false`	Show the plan without writing.
`--auto-approve`	Boolean	`false`	Create without an interactive confirmation.

update

Updates one exact agent from a local definition. Names are not unique, so the stable ID is required. Usage

atlanai agent update <agent-id> --file <agent.yaml> [flags]

Option	Type	Default	Description
`--file`, `-f`	path	required	Agent YAML or JSON definition.
`--dry-run`	Boolean	`false`	Show the plan without writing.
`--auto-approve`	Boolean	`false`	Update without an interactive confirmation.

Examples

atlanai agent validate ./agent.yaml
atlanai agent create --file ./agent.yaml --workspace workspace_123 --dry-run
atlanai agent list --provider provider_123 --json id,name,model_id
atlanai agent search "incident response" --strategy hybrid
atlanai agent get agent_123
atlanai agent update agent_123 --file ./agent.yaml --dry-run

Output and behavior

list, search, and get return human output unless --json, --jq, or --template is supplied.
validate rejects unknown fields and invalid tool definitions locally.
create and update prompt before writing unless --auto-approve is used.
update reads the current content hash and refuses an unconditional update.
Agent creation does not print or store the Registry’s reveal-once machine credential.

Overview

CLI

SDK

Cookbooks

Operate safely

API reference

Commands

list

search

get

validate

create

update

Examples

Output and behavior

​Commands

​list

​search

​get

​validate

​create

​update

​Examples

​Output and behavior

​Related

Commands

list

search

get

validate

create

update

Examples

Output and behavior

Related