> ## Documentation Index
> Fetch the complete documentation index at: https://platform.atlan.com/llms.txt
> Use this file to discover all available pages before exploring further.

> ## Agent Instructions
> To act on Atlan objects, use the Atlan MCP server at https://api.atlan.com/mcp or the atlanai CLI; `atlanai --map json` prints its command map. Run a read-only identity check before any write.
> The docs MCP server at /mcp searches these docs only. It cannot read or change Atlan objects.
> SDK packages: Python `atlanai` (PyPI) and TypeScript `@atlanai/sdk` (npm). Show Python first, then TypeScript.

# atlanai agent

> Validate, create, find, inspect, and update agent records.

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

## Commands

### list

Lists agents visible to the authenticated identity.

**Usage**

```text theme={null}
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**

```text theme={null}
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**

```text theme={null}
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**

```text theme={null}
atlanai agent validate <agent.yaml>
```

### create

Creates an agent from a local YAML or JSON definition.

**Usage**

```text theme={null}
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**

```text theme={null}
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

```bash theme={null}
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.

## Related

* [Work with Registry](/tools/cli/how-tos/registry)
* [`atlanai harness`](/tools/cli/references/commands/harness)
* [`atlanai workspace`](/tools/cli/references/commands/workspace)
* [`atlanai context`](/tools/cli/references/commands/context)