Managing your agents

Once an agent is deployed it runs continuously until you pause or delete it. Use the ast agent commands to manage it over its lifetime.

Commands that target a deployment require exactly one of --name (display name or blueprint name from agent list) or --id (deployment ID from agent list). Quote --name when it contains spaces or special characters.

Inspect

List all agents in the active account:

$
ast agent list

Get full details for a specific agent:

$
ast agent get --name "My Production Agent"
$
ast agent get --id ze5-r2l-m16

Display names are set at deploy time (--name on deploy). Use --id when you need an unambiguous target (e.g. duplicate display names).

Observe

Fetch recent logs from all containers in the agent workload:

$
ast agent logs --name "My Production Agent"

Stream logs continuously as they arrive:

$
ast agent logs --name "My Production Agent" --tail

To fetch logs from the messaging sidecar instead:

$
ast agent logs --name "My Production Agent" --workload agent/messaging

--workload also targets non-agent workloads — knowledge entries, ingestion sidecars, or the telemetry collector. Pass either a full workload name (my-agent-knowledge-vectors), an entry-name suffix (vectors), or a component label (knowledge, collector):

$
ast agent logs --name "My Production Agent" --workload vectors
$
ast agent logs --name "My Production Agent" --workload collector

Append /<container> to pick a specific container in the resolved workload. Run ast agent get --name "My Production Agent" to see each workload’s K8s name.

List recent traces (live Langfuse; the same Monitor data as the web UI):

$
ast agent trace --name "My Production Agent"

Show the activity summary from the /agents dashboard (sparkline, last active, totals). Use this when you want to match what the card shows without querying Langfuse directly; data updates about every 10 minutes. --summary ignores list window flags (--limit, --start, etc.).

$
ast agent trace --name "My Production Agent" --summary

Show a single trace Overview — input, output, observations, and scores:

$
ast agent trace --name "My Production Agent" --trace-id 2dc10d31ac3ebec7dd9d27263dd7531d

Filter by time window or paginate (defaults match the server: --limit 50):

$
ast agent trace --name "My Production Agent" --start 2026-05-28T00:00:00Z --end 2026-05-28T23:59:59Z --limit 10 --offset 0

Pass --json to emit the raw API response for scripting.

Control

Pause an agent to stop it from handling requests without deleting it:

$
ast agent pause --name "My Production Agent"

Resume it when ready:

$
ast agent resume --name "My Production Agent"

Restart the agent process in-place (useful after a transient failure):

$
ast agent restart --name "My Production Agent" --component agent

Update

Redeploy an existing agent in-place (without changing its deployment ID or URL) to pick up new variables or a different build:

$
ast agent redeploy --name "My Production Agent" --var ANTHROPIC_API_KEY=@ANTHROPIC_API_KEY

This is the right command after rotating a secret or pushing a new blueprint build. It accepts the same --var, --vars-file, --adapter, and --build flags as ast blueprint deploy. If --adapter is omitted, the adapter defaults to web; pass it explicitly to preserve or change a non-web setup.

Delete

$
ast agent delete --name "My Production Agent"

You will be prompted to confirm. Pass --confirm with the display name or deployment ID to skip the prompt in scripts.