# amctl agent

Manage agents in a project — create, build, deploy, inspect, and observe.

```
amctl agent [command]
```

## Subcommands[​](#subcommands "Direct link to Subcommands")

| Command                                       | Purpose                                      |
| --------------------------------------------- | -------------------------------------------- |
| [`create`](#amctl-agent-create)               | Create an agent                              |
| [`get`](#amctl-agent-get)                     | Show details of an agent                     |
| [`list`](#amctl-agent-list)                   | List agents in a project                     |
| [`delete`](#amctl-agent-delete)               | Delete an agent                              |
| [`deploy`](#amctl-agent-deploy)               | Deploy a built agent image to an environment |
| [`build create`](#amctl-agent-build-create)   | Trigger a build                              |
| [`build get`](#amctl-agent-build-get)         | Show details of a build                      |
| [`build list`](#amctl-agent-build-list)       | List builds for an agent                     |
| [`build logs`](#amctl-agent-build-logs)       | Show build logs                              |
| [`logs`](#amctl-agent-logs)                   | Fetch runtime logs for a deployed agent      |
| [`metrics`](#amctl-agent-metrics)             | Show CPU and memory metrics                  |
| [`traces`](#amctl-agent-traces)               | List runtime traces                          |
| [`traces export`](#amctl-agent-traces-export) | Export a full trace payload                  |
| [`trace`](#amctl-agent-trace)                 | Show span detail for a single trace          |

## Options inherited from parent commands[​](#options-inherited-from-parent-commands "Direct link to Options inherited from parent commands")

| Name        | Description                                                    |
| ----------- | -------------------------------------------------------------- |
| `--project` | Project that owns the agent. Falls back to the linked project. |
| `--org`     | Override the active organization.                              |
| `--json`    | Output as JSON envelopes.                                      |

Runtime-managed agents only

`logs`, `metrics`, `traces`, `trace`, and `traces export` only work for platform-managed agents. Calling them against an external-runtime agent fails up-front with a clear error.

***

## amctl agent create[​](#amctl-agent-create "Direct link to amctl agent create")

Create an agent in the active project.

```
amctl agent create <name> [flags]
```

### Arguments[​](#arguments "Direct link to Arguments")

| Name     | Description                 |
| -------- | --------------------------- |
| `<name>` | Agent name (URL-safe slug). |

### Examples[​](#examples "Direct link to Examples")

```
# Chat API agent built from a public repo with buildpacks
amctl agent create support-bot \
  --display-name "Support Bot" \
  --subtype chat-api \
  --repo-url https://github.com/acme/support-bot \
  --repo-branch main \
  --build-type buildpack \
  --language python \
  --language-version 3.12

# Custom-API agent with a Dockerfile build
amctl agent create checkout-api \
  --display-name "Checkout API" \
  --subtype custom-api \
  --repo-url https://github.com/acme/checkout-api \
  --build-type docker \
  --dockerfile Dockerfile \
  --port 8080 \
  --openapi-spec openapi.yaml

# Plain environment + secret references
amctl agent create payments \
  --display-name "Payments" \
  --subtype custom-api \
  --repo-url https://github.com/acme/payments \
  --env LOG_LEVEL=info \
  --env-secret STRIPE_KEY=sk_test_xxx \
  --env-from-secret OPENAI_API_KEY=shared-openai
```

### Options[​](#options "Direct link to Options")

| Name                        | Type    | Default    | Description                                                               |
| --------------------------- | ------- | ---------- | ------------------------------------------------------------------------- |
| `--display-name`            | string  | *required* | Human-readable name.                                                      |
| `--description`             | string  | (none)     | Free-text description.                                                    |
| `--subtype`                 | string  | (none)     | Agent sub-type: `chat-api` or `custom-api`.                               |
| `--provisioning`            | string  | `internal` | `internal` (platform-managed) or `external`.                              |
| `--repo-url`                | string  | (none)     | Source repository URL.                                                    |
| `--repo-branch`             | string  | (none)     | Source branch.                                                            |
| `--repo-path`               | string  | (none)     | Application path within the repository.                                   |
| `--repo-secret`             | string  | (none)     | Secret reference for private repositories.                                |
| `--build-type`              | string  | (none)     | `buildpack` or `docker`.                                                  |
| `--language`                | string  | (none)     | Language for buildpack builds.                                            |
| `--language-version`        | string  | (none)     | Language version for buildpack builds.                                    |
| `--run-command`             | string  | (none)     | Run command for buildpack builds.                                         |
| `--dockerfile`              | string  | (none)     | Dockerfile path (Docker builds).                                          |
| `--port`                    | int     | `8000`     | Service port (1–65535). Applies only to `custom-api`.                     |
| `--base-path`               | string  | (none)     | Base path for the agent's HTTP service.                                   |
| `--openapi-spec`            | string  | (none)     | Path to OpenAPI schema within the repo.                                   |
| `--no-auto-instrumentation` | bool    | `false`    | Disable automatic instrumentation.                                        |
| `--env`                     | strings | (none)     | Environment variable as `KEY=VALUE`. Repeatable. Stored as plain text.    |
| `--env-secret`              | strings | (none)     | Sensitive env variable as `KEY=VALUE`. Repeatable.                        |
| `--env-from-secret`         | strings | (none)     | Env variable sourced from a managed secret: `KEY=SECRETNAME`. Repeatable. |
| `--model-config-file`       | string  | (none)     | Path to a model-config YAML/JSON file.                                    |

***

## amctl agent get[​](#amctl-agent-get "Direct link to amctl agent get")

Show configuration and current build/deploy status for an agent.

```
amctl agent get [agent]
```

### Arguments[​](#arguments-1 "Direct link to Arguments")

| Name      | Description                                      |
| --------- | ------------------------------------------------ |
| `[agent]` | Agent name. Optional if the directory is linked. |

note

`agent get` returns the agent's **configured** state, not its **runtime** liveness. Use [`amctl agent logs`](#amctl-agent-logs), [`amctl agent metrics`](#amctl-agent-metrics), or [`amctl agent traces`](#amctl-agent-traces) to check that a deployed agent is actually serving.

***

## amctl agent list[​](#amctl-agent-list "Direct link to amctl agent list")

List agents in the active project.

```
amctl agent list [flags]
```

### Options[​](#options-1 "Direct link to Options")

| Name       | Type | Default          | Description                |
| ---------- | ---- | ---------------- | -------------------------- |
| `--limit`  | int  | (server default) | Maximum number of results. |
| `--offset` | int  | `0`              | Number of results to skip. |

***

## amctl agent delete[​](#amctl-agent-delete "Direct link to amctl agent delete")

Delete an agent. Asks for confirmation unless `--yes` is set. Deletes are asynchronous — the agent enters a terminating state immediately and is fully removed shortly after.

```
amctl agent delete [agent] [flags]
```

### Arguments[​](#arguments-2 "Direct link to Arguments")

| Name      | Description                                      |
| --------- | ------------------------------------------------ |
| `[agent]` | Agent name. Optional if the directory is linked. |

### Options[​](#options-2 "Direct link to Options")

| Name    | Short | Type | Default | Description                   |
| ------- | ----- | ---- | ------- | ----------------------------- |
| `--yes` | `-y`  | bool | `false` | Skip the confirmation prompt. |

***

## amctl agent deploy[​](#amctl-agent-deploy "Direct link to amctl agent deploy")

Deploy a built agent image to the lowest environment in the deployment pipeline.

Env vars passed via `--env` are merged with the agent's current configuration. Conflicting values require interactive confirmation or `--yes`. CLI-supplied values are always stored as plain text — use the platform UI or `--env-from-secret` at create-time for secrets.

```
amctl agent deploy [agent] [flags]
```

### Arguments[​](#arguments-3 "Direct link to Arguments")

| Name      | Description                                      |
| --------- | ------------------------------------------------ |
| `[agent]` | Agent name. Optional if the directory is linked. |

### Examples[​](#examples-1 "Direct link to Examples")

```
# Deploy the latest build of the linked agent
amctl agent deploy

# Deploy a specific build by buildName
amctl agent deploy support-bot --build-name support-bot-build-3

# Merge two env vars, skip the conflict prompt
amctl agent deploy --env LOG_LEVEL=debug --env FEATURE_X=true --yes
```

### Options[​](#options-3 "Direct link to Options")

| Name           | Short | Type    | Default                 | Description                                                          |
| -------------- | ----- | ------- | ----------------------- | -------------------------------------------------------------------- |
| `--build-name` |       | string  | *latest by `startedAt`* | Build to deploy. Builds are addressed by `buildName`, not `buildId`. |
| `--env`        |       | strings | (none)                  | Set env var as `KEY=VALUE`. Repeatable. Merges with current config.  |
| `--yes`        | `-y`  | bool    | `false`                 | Skip the env-conflict confirmation prompt.                           |

***

## amctl agent build create[​](#amctl-agent-build-create "Direct link to amctl agent build create")

Trigger a build for an agent.

```
amctl agent build create [agent] [flags]
```

### Arguments[​](#arguments-4 "Direct link to Arguments")

| Name      | Description                                      |
| --------- | ------------------------------------------------ |
| `[agent]` | Agent name. Optional if the directory is linked. |

### Options[​](#options-4 "Direct link to Options")

| Name       | Type   | Default  | Description               |
| ---------- | ------ | -------- | ------------------------- |
| `--commit` | string | (latest) | Commit SHA to build from. |

***

## amctl agent build get[​](#amctl-agent-build-get "Direct link to amctl agent build get")

Show details of a build.

```
amctl agent build get [agent] <build-name>
```

### Arguments[​](#arguments-5 "Direct link to Arguments")

| Name           | Description                                            |
| -------------- | ------------------------------------------------------ |
| `[agent]`      | Agent name. Optional if the directory is linked.       |
| `<build-name>` | Build to display. Builds are addressed by `buildName`. |

### Example[​](#example "Direct link to Example")

```
amctl agent build get support-bot support-bot-build-3
```

***

## amctl agent build list[​](#amctl-agent-build-list "Direct link to amctl agent build list")

List builds for an agent.

```
amctl agent build list [agent] [flags]
```

### Arguments[​](#arguments-6 "Direct link to Arguments")

| Name      | Description                                      |
| --------- | ------------------------------------------------ |
| `[agent]` | Agent name. Optional if the directory is linked. |

### Options[​](#options-5 "Direct link to Options")

| Name       | Type | Default          | Description                |
| ---------- | ---- | ---------------- | -------------------------- |
| `--limit`  | int  | (server default) | Maximum number of results. |
| `--offset` | int  | `0`              | Number of results to skip. |

***

## amctl agent build logs[​](#amctl-agent-build-logs "Direct link to amctl agent build logs")

Show logs for a build. Output is raw text, not JSON — `--json` is ignored.

```
amctl agent build logs [agent] [build-name]
```

### Arguments[​](#arguments-7 "Direct link to Arguments")

| Name           | Description                                             |
| -------------- | ------------------------------------------------------- |
| `[agent]`      | Agent name. Optional if the directory is linked.        |
| `[build-name]` | Build name. Defaults to the latest build for the agent. |

### Example[​](#example-1 "Direct link to Example")

```
# Latest build of the linked agent
amctl agent build logs

# Specific build
amctl agent build logs support-bot support-bot-build-3
```

***

## amctl agent logs[​](#amctl-agent-logs "Direct link to amctl agent logs")

Fetch runtime logs for a deployed agent.

```
amctl agent logs <agent> [flags]
```

### Arguments[​](#arguments-8 "Direct link to Arguments")

| Name      | Description                                      |
| --------- | ------------------------------------------------ |
| `<agent>` | Agent name. Optional if the directory is linked. |

### Examples[​](#examples-2 "Direct link to Examples")

```
# Last hour of ERROR-level logs
amctl agent logs support-bot --since 1h --level ERROR

# Search across the last day
amctl agent logs support-bot --grep "tool_call_failed"

# Latest 100 lines, JSON for downstream parsing
amctl agent logs support-bot --limit 100 --json | jq '.data.logs[]'
```

### Options[​](#options-6 "Direct link to Options")

| Name      | Type    | Default          | Description                                                    |
| --------- | ------- | ---------------- | -------------------------------------------------------------- |
| `--since` | string  | `24h`            | Time window. Examples: `30m`, `1h`, `7d`.                      |
| `--level` | strings | (all)            | Filter by level: `DEBUG`, `INFO`, `WARN`, `ERROR`. Repeatable. |
| `--grep`  | string  | (none)           | Substring filter applied server-side.                          |
| `--limit` | int     | (server default) | Maximum entries (1–10000).                                     |
| `--sort`  | string  | `desc`           | `asc` (oldest first) or `desc` (newest first).                 |
| `--env`   | string  | (linked env)     | Environment to query.                                          |

***

## amctl agent metrics[​](#amctl-agent-metrics "Direct link to amctl agent metrics")

Show CPU and memory usage against the agent's request and limit values, sampled over a time window. The default text output is a table; `--json` returns the raw timeseries arrays.

```
amctl agent metrics <agent> [flags]
```

### Arguments[​](#arguments-9 "Direct link to Arguments")

| Name      | Description                                      |
| --------- | ------------------------------------------------ |
| `<agent>` | Agent name. Optional if the directory is linked. |

### Example[​](#example-2 "Direct link to Example")

```
amctl agent metrics support-bot --since 1h
```

Output:

```
metric  current  request  limit
CPU     120m     250m     500m
Memory  340Mi    512Mi    1.0Gi
```

### Options[​](#options-7 "Direct link to Options")

| Name      | Type   | Default      | Description                               |
| --------- | ------ | ------------ | ----------------------------------------- |
| `--since` | string | `24h`        | Time window. Examples: `30m`, `1h`, `7d`. |
| `--env`   | string | (linked env) | Environment to query.                     |

***

## amctl agent traces[​](#amctl-agent-traces "Direct link to amctl agent traces")

List runtime traces for an agent, optionally filtered by a built-in condition.

```
amctl agent traces <agent> [flags]
```

### Arguments[​](#arguments-10 "Direct link to Arguments")

| Name      | Description                                      |
| --------- | ------------------------------------------------ |
| `<agent>` | Agent name. Optional if the directory is linked. |

### Examples[​](#examples-3 "Direct link to Examples")

```
# Last 2 hours of errored traces
amctl agent traces support-bot --since 2h --condition error_status

# Slow requests (over 60 seconds)
amctl agent traces support-bot --condition high_latency --max-latency 60000

# Tool failures
amctl agent traces support-bot --condition tool_call_fails
```

### Options[​](#options-8 "Direct link to Options")

| Name            | Type   | Default      | Description                                                                                       |
| --------------- | ------ | ------------ | ------------------------------------------------------------------------------------------------- |
| `--since`       | string | `24h`        | Time window.                                                                                      |
| `--limit`       | int    | `10`         | Maximum traces (1–100).                                                                           |
| `--sort`        | string | `desc`       | `asc` or `desc`.                                                                                  |
| `--condition`   | string | (none)       | One of: `error_status`, `high_latency`, `high_token_usage`, `tool_call_fails`, `excessive_steps`. |
| `--max-latency` | int    | `30000`      | Latency threshold in milliseconds (used with `high_latency`).                                     |
| `--max-tokens`  | int    | `10000`      | Token threshold (used with `high_token_usage`).                                                   |
| `--max-spans`   | int    | `40`         | Span-count threshold (used with `excessive_steps`).                                               |
| `--env`         | string | (linked env) | Environment to query.                                                                             |

***

## amctl agent traces export[​](#amctl-agent-traces-export "Direct link to amctl agent traces export")

Export a single trace's full payload, including every span and span event. Suitable for offline analysis or attaching to an incident ticket.

```
amctl agent traces export <agent> <trace-id> [flags]
```

### Arguments[​](#arguments-11 "Direct link to Arguments")

| Name         | Description                                                                    |
| ------------ | ------------------------------------------------------------------------------ |
| `<agent>`    | Agent name. Optional if the directory is linked.                               |
| `<trace-id>` | Trace ID, typically obtained from [`amctl agent traces`](#amctl-agent-traces). |

### Example[​](#example-3 "Direct link to Example")

```
amctl agent traces export support-bot 7c8f...e1 --since 1h > trace.json
```

### Options[​](#options-9 "Direct link to Options")

| Name      | Type   | Default      | Description                            |
| --------- | ------ | ------------ | -------------------------------------- |
| `--since` | string | *required*   | Time window the trace was produced in. |
| `--limit` | int    | `100`        | Maximum spans to include (1–100).      |
| `--sort`  | string | `desc`       | Span order: `asc` or `desc`.           |
| `--env`   | string | (linked env) | Environment to query.                  |

***

## amctl agent trace[​](#amctl-agent-trace "Direct link to amctl agent trace")

Show span details for a single trace. With `--span`, expand a specific span to full detail.

```
amctl agent trace <agent> <trace-id> [flags]
```

### Arguments[​](#arguments-12 "Direct link to Arguments")

| Name         | Description                                      |
| ------------ | ------------------------------------------------ |
| `<agent>`    | Agent name. Optional if the directory is linked. |
| `<trace-id>` | Trace ID.                                        |

### Examples[​](#examples-4 "Direct link to Examples")

```
# Span summary
amctl agent trace support-bot 7c8f...e1

# Full detail for a specific span
amctl agent trace support-bot 7c8f...e1 --span a2b3...c4
```

### Options[​](#options-10 "Direct link to Options")

| Name      | Type   | Default      | Description                             |
| --------- | ------ | ------------ | --------------------------------------- |
| `--since` | string | `24h`        | Time window to search.                  |
| `--span`  | string | (none)       | Show full detail for the given span ID. |
| `--limit` | int    | `1000`       | Maximum spans to return.                |
| `--env`   | string | (linked env) | Environment to query.                   |

## See Also[​](#see-also "Direct link to See Also")

* [`amctl project`](/agent-manager/docs/next/cli/project/.md) — manage projects that own agents
* [`amctl context link`](/agent-manager/docs/next/cli/context/.md#amctl-context-link) — link the current directory to an agent
* [Observe your first agent](/agent-manager/docs/next/tutorials/observe-first-agent/.md)