> For clean Markdown of any page, append .md to the page URL.
> For a complete documentation index, see https://docs.astropods.com/llms.txt.
> For AI client integration (Claude Code, Cursor, etc.), connect to the MCP server at https://docs.astropods.com/_mcp/server.

# ast agent

Manage deployed agents in the active account.

```bash
ast agent <subcommand>
```

Commands that target a deployment require exactly one of `--name` (display name or blueprint name from `agent list`) or `--id` (deployment ID). Quote `--name` values that contain spaces or shell metacharacters, e.g. `ast agent get --name 'Pirate Parrot EU!'`.

## agent list

```bash
ast agent list [--json]
```

## agent get

```bash
ast agent get --name <display-or-blueprint-name> [--json]
ast agent get --id <deployment-id> [--json]
```

## agent pause / resume

```bash
ast agent pause --name <display-or-blueprint-name>
ast agent pause --id <deployment-id>
ast agent resume --name <display-or-blueprint-name>
ast agent resume --id <deployment-id>
```

## agent redeploy

Re-deploy an existing agent in-place. Accepts the same `--adapter`, `--var`, `--vars-file`, `--schedule`, `--build`, `--cluster`, `--dry-run`, `--wait`, and `--json` flags as [`blueprint deploy`](/cli/blueprint#blueprint-deploy). If `--adapter` is omitted, the adapter defaults to `web`; pass `--adapter` explicitly to preserve or change a non-web setup.

`--cluster` moves the agent to another cluster. The agent restarts on the new cluster, and the old one is torn down. Without `--cluster`, the agent stays on its current cluster.

`--schedule` changes the cadence of a scheduled ingestion job. A job you do not name keeps the cron it already has, so you only pass the ones you want to change. See [Schedule an ingestion job](/cli/blueprint#schedule-an-ingestion-job).

```bash
ast agent redeploy --name <display-or-blueprint-name> [flags]
ast agent redeploy --id <deployment-id> [flags]
```

## agent restart

```bash
ast agent restart --name <display-or-blueprint-name> --component agent
ast agent restart --id <deployment-id> --component agent
```

## agent trigger

Run one of an agent's ingestion jobs once, straight away, without waiting for
its schedule.

```bash
ast agent trigger <ingestion> --name <display-or-blueprint-name>
ast agent trigger <ingestion> --id <deployment-id>
```

Omit the ingestion name to list the agent's ingestion jobs, with the cron
expression of any that run on a schedule:

```bash
$ ast agent trigger --name my-agent
Ingestion jobs on my-agent:

  docs_sync  (*/15 * * * *)
  metrics_rollup  (0 9 * * 1)
```

This works for an ingestion whose trigger type is `schedule` as well as one set
to `manual`, so you can confirm a cadence you set with
[`--schedule`](/cli/blueprint#schedule-an-ingestion-job) does what you expect
instead of waiting for the next run. An ingestion triggered by a webhook or at
startup cannot be run this way.

Triggering an ingestion that is already running returns a conflict and starts
nothing, so a run you can see in progress will not be duplicated. Two triggers
sent at the same moment, or one sent as a scheduled run begins, can still
overlap. If a job must never run twice, make it safe to run twice rather than
relying on this check.

## agent logs

```bash
ast agent logs --name <display-or-blueprint-name> [--workload <workload>[/<container>]] [--tail]
ast agent logs --id <deployment-id> [--workload <workload>[/<container>]] [--tail]
```

By default this reads logs from all containers in the agent workload. Use `--workload` to target a different workload (knowledge entry, ingestion sidecar, collector, etc.) or a specific container.

`--workload` accepts any of:

* A full workload name: `my-agent-knowledge-vectors`
* An entry-name suffix: `vectors` (matches `my-agent-knowledge-vectors`)
* A component label: `agent`, `messaging`, `knowledge`, `collector`
* A `workload/container` pair to pick a specific container: `agent/messaging`

Ambiguous identifiers (e.g. `knowledge` when several knowledge entries exist) return an error listing the candidates. Use `ast agent get --name <display-or-blueprint-name>` to see each workload's name.

`--tail` streams logs continuously after fetching the last 15 minutes.

## agent delete

```bash
ast agent delete --name <display-or-blueprint-name> [--confirm <name-or-id>]
ast agent delete --id <deployment-id> [--confirm <name-or-id>]
```

Prompts for confirmation. Pass `--confirm` with the display name or deployment ID to skip the prompt.

## agent history

```bash
ast agent history --name <display-or-blueprint-name> [--json]
ast agent history --id <deployment-id> [--json]
```

## agent trace

List recent traces for a deployed agent (live trace query; same data as the Monitor tab in the web UI; default `--limit` is 50):

```bash
ast agent trace --name <display-or-blueprint-name> [--limit <n>] [--offset <n>] [--start <RFC3339>] [--end <RFC3339>] [--json]
ast agent trace --id <deployment-id> [--limit <n>] [--offset <n>] [--start <RFC3339>] [--end <RFC3339>] [--json]
```

Show a single trace Overview (input, output, metadata, observations, scores):

```bash
ast agent trace --name <display-or-blueprint-name> --trace-id <trace-id> [--json]
ast agent trace --name <display-or-blueprint-name> -t <trace-id> [--json]
ast agent trace --id <deployment-id> --trace-id <trace-id> [--json]
```

Print the agents-page activity summary (30-day request/token sparkline, total traces, last active). Matches the `/agents` dashboard, not a live trace query. Does not use `--limit`, `--offset`, `--start`, or `--end`. Cannot be combined with `--trace-id`.

```bash
ast agent trace --name <display-or-blueprint-name> --summary [--json]
ast agent trace --id <deployment-id> --summary [--json]
```

## Next steps

* [Managing your agents](/managing-agents): the same operations from the web console
* [Troubleshooting stuck deployments](/troubleshooting-deployments): recover a deploy that never goes live
* [ast blueprint](/cli/blueprint): build, push, and deploy blueprints