Skip to navigation
Commands

ast agent

Inspect, control, and remove deployed agents
View as Markdown

Manage deployed agents in the active account.

ast agent <subcommand>

Commands that target a deployment require exactly one of:

  • --name: a display name, or a blueprint name from agent list. A blueprint name that matches several agents fails and lists them; pick one with --id or --env.
  • --id: a deployment ID.
  • --env: the environment the agent runs in. The blueprint comes from --blueprint, or from astropods.yml in the current directory.

Quote --name values that contain spaces or shell metacharacters, e.g. ast agent get --name 'Pirate Parrot EU!'.

agent list

ast agent list [--json]

Shows each agent’s environment. agent get shows it too.

agent get

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

agent pause / resume

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. 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 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 a job.

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

agent restart

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 jobs once, straight away, without waiting for its schedule.

ast agent trigger <job> --name <display-or-blueprint-name>
ast agent trigger <job> --id <deployment-id>

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

$ ast agent trigger --name my-agent
Ingestion jobs on my-agent:
  docs_sync  (*/15 * * * *)
  metrics_rollup  (0 9 * * 1)

This works for a job whose trigger type is schedule as well as one set to manual, so you can confirm a cadence you set with --schedule does what you expect instead of waiting for the next run. A job triggered by a webhook or at startup cannot be run this way.

Triggering a job 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

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

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

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):

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):

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.

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

Next steps