Skip to content

Run an agent and read its results#

This page covers starting a run, following it to the end, and reading what it did: its output, its trace (model and tool calls with the gateway's decisions), its activity (everything that left it) and its cost. For the receipt, see Verify a receipt.

Before you begin#

  • An agent (see Create and change an agent) and the editor or admin role to run it. Viewers read runs.
  • For the API: ASTRA_TOKEN and WS as in the REST API page. The CLI has no command to start an agent run; astra astraeus logs <run> and astra astraeus delete <run> work on agent runs as on any run.

Start a run#

  1. On the agent's page press Run agent.
  2. Input: what the agent is asked (it reads it from /agent/input).
  3. Version: the current one by default.
  4. Press Run. The run's page opens.
$ curl -sS -X POST "$WS/agents/researcher/runs" -H "Authorization: Bearer $ASTRA_TOKEN" \
    -H "Content-Type: application/json" \
    -d '{"input": "What changed in the latest stable Rust release?"}' | jq -r .run.metadata.name
researcher-d2b797

{"input", "version"?}; the input is required, at most 256 KiB. Without version, the current version runs — or, during a traffic split, the version the run's name falls to. The answer is 201 with agent, version, input and run (the run with its state and worker).

A run is refused when it is made if a budget of its agent or workspace is spent (409 BUDGET_EXHAUSTED), if its model's deployment has no endpoint yet (400 INVALID_AGENT), or as any run is (quotas, invalid template).

Follow it#

The run is Pending while it waits for a machine, Running, then Completed, Failed or Cancelled. A run waiting for approval says so on its page and in its agent's Runs list (see Handle approvals).

The run's page refreshes itself: state and reason, Input, Output (the agent's standard output as it is written), and the Trace, Activity and Receipt tabs. As a run opens the same run in Astraeus (its worker, machine, events, metrics).

$ astra astraeus status researcher-d2b797
$ astra astraeus logs researcher-d2b797

$ curl -sS "$WS/agents/researcher/runs/researcher-d2b797" -H "Authorization: Bearer $ASTRA_TOKEN" \
    | jq '{version, state: .run.status.state, reason: .run.status.reason, waiting: .waiting_for_approval, spend}'
$ curl -sS "$WS/tasks/researcher-d2b797-0/logs?tail=500" -H "Authorization: Bearer $ASTRA_TOKEN" | jq -r .logs

Read the trace and the activity#

Trace shows totals — Model calls, Input tokens, Output tokens, Tool calls, Provider's tools, Cost — then each step: model calls with their model, route and tokens; tool calls with the target (github/issue_read, github GET api.github.com/repos/…), the decision (allowed, denied, approval required), the rule that decided and the reason.

Activity lists everything that left the run — each request with its URL, each connection and DNS lookup, tool and model calls, the provider's own tools — allowed or refused, and by what.

$ curl -sS "$WS/tasks/researcher-d2b797-0/trace?limit=500" -H "Authorization: Bearer $ASTRA_TOKEN"
$ curl -sS "$WS/tasks/researcher-d2b797-0/activity" -H "Authorization: Bearer $ASTRA_TOKEN"

trace gives the latest steps (500 by default, at most 2 000). With canonical=1&format=jsonl it gives every step as the line the receipt's Merkle root is built from (see Verify a receipt).

Both are read from the run's machine when you ask: if the machine is offline, they cannot be shown. Machines keep them 7 days after the run is gone from them by default (retention).

What it cost#

The run's page shows its cost; the agent's Costs tab lists each run's model calls, tokens and cost for Today or This month; Anemoi → Budgets shows the whole workspace.

$ curl -sS "$WS/agents/researcher/costs?period=month" -H "Authorization: Bearer $ASTRA_TOKEN"
$ curl -sS "$WS/agent-costs?period=day" -H "Authorization: Bearer $ASTRA_TOKEN"

period is day (the default) or month, in UTC.

List an agent's runs#

The agent's Runs tab: run, version, state (and waiting for approval), who started it, when, and cost.

$ curl -sS "$WS/agents/researcher/runs" -H "Authorization: Bearer $ASTRA_TOKEN" \
    | jq -r '.items[] | [.name, .version, .state, (.spend.cost_usd // 0)] | @tsv'

Newest first. Runs made by evaluations are not listed.

Stop a run#

Open the run As a run and delete it: its worker stops, and its receipt is made with Cancelled.

$ astra astraeus delete researcher-d2b797

$ curl -sS -X DELETE "$WS/jobs/researcher-d2b797" -H "Authorization: Bearer $ASTRA_TOKEN"

Troubleshooting#

Symptom Cause Fix
The run stays Pending: machine cannot run agents in OpenShell No machine of the workspace can run agents. A Linux machine with kernel 6.2 or newer and the current machine package, not running workers on its host network. See FAQ.
A tool call is denied: no policy permits it No permit matches it. Add or widen a rule; use Test a call.
A tool call is denied with a reason you did not write A workspace or organisation guardrail forbids it. See Anemoi → Guardrails.
budget reached: $2.00 of $2.00 in the output The run's own limit. Raise budget.max_cost_usd, or use Ask for approval.
The agent says it could not reach a host The sandbox allows no such host. Add it to the sandbox policy (Test a host).
The trace is empty, No trace yet The run has not called anything yet, or its machine is offline. Wait, or check the machine.