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

# 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](/cli/registry)
* [`atlanai harness`](/cli/reference/harness)
* [`atlanai workspace`](/cli/reference/workspace)
* [`atlanai context`](/cli/reference/context)