Skip to main content

Runs

The Runs screen lets you list the agent executions of the tenant, open one to follow its timeline, its budgets and its checkpoints, and resume, cancel or replay it. Portal path: /agents/runs (detail page: /agents/runs/<run-id>). Developers, runtime operators, auditors and security officers use it to follow and investigate executions. The screen is drawn by portal/src/screens/agents.tsx.

What the screen shows​

The list page:

  • Runs table, read with GET /v1/runs (50 rows per call, newest first, cursor paging). Columns: Run id, Agent, Agent version, State, Trigger, Depth (0 for a root run, more for a sub-agent), Created by, Created.
  • Filters State (Queued, Running, Waiting approval, Succeeded, Failed, Cancelled, or all) and Agent (agent id or name), then Filter.
  • When the list is empty: No run yet, with the hint Start a run from an agent detail page. Runs start from the Registry, a schedule, a trigger or a channel; this screen has no create button.
  • A click on a row, or the row menu View details, opens the run page.

The run page (GET /v1/runs/{run_id}):

  • Back, the title Run, the run id, the objective (task.objective) and the state badge.
  • The buttons Resume, Cancel and Replay.
  • Budget cards: one card per consumed budget with its Limit when one is set, or No budget recorded for this run.
  • Execution timeline: the steps of the run (GET /v1/runs/{run_id}/steps) with their name, kind, state, start and end dates, attempt, tokens and cost. When the run has sub-agents (GET /v1/runs/{run_id}/subagents), the timeline nests the sub-agent runs under the steps. No step yet when there is none.
  • Checkpoints: the checkpoints of the run (GET /v1/runs/{run_id}/checkpoints), or No checkpoint.
  • Replay: the replay of the run, shown after a click on Replay.
  • Execution Contract: the full run document in JSON.

While the run is queued or running, the page reads the run again every 3 seconds; while it is queued, running or waiting for an approval it also follows the live events (GET /v1/runs/{run_id}/events with follow=true) and refreshes the run, its steps and its checkpoints at each event.

Actions​

Button or actionWhat it doesAPI callRoles
Refresh (icon)Reloads the list.GET /v1/runsAny tenant member
FilterApplies the State and Agent filters.GET /v1/runs with state and agentAny tenant member
Row click or row menu View detailsOpens the run page.GET /v1/runs/{run_id}Any tenant member
Row menu Configuration evidenceShows in a side panel the configuration the run really used: agent version and manifest digest, recorded models, prompts, tools, skills and plugins, and the policy decisions of the run.GET /v1/evidence/runs/{run_id}/configurationauditor, security_officer, tenant_admin, agent_operator, developer
Back (run page)Returns to the list.NoneEveryone
ResumeResumes a suspended, failed, timed out or waiting for input run, from its last checkpoint (or by restarting the step when it waits for input).POST /v1/runs/{run_id}/resumetenant_admin, developer, agent
CancelAsks Cancel this run?, then cancels the run.POST /v1/runs/{run_id}/canceltenant_admin, developer, agent, security_officer
ReplayReads the ordered timeline of the run (steps, checkpoints, run events and audit events) and shows it in the Replay section.GET /v1/runs/{run_id}/replaytenant_admin, developer, agent, auditor, security_officer
Retry (error state)Sends the failed read again.Same callSame roles

Roles​

The portal hides no button on this screen; the Control Plane answers forbidden (403) with required_roles when a role is missing. In services/control-plane/src/eai/domains/agents/routes.py, reading the runs, steps, checkpoints, sub-agents and events only needs a tenant; resume uses OPS_ROLES (tenant_admin, developer, agent), cancel adds security_officer, replay adds auditor and security_officer. The configuration evidence uses the readers of services/control-plane/src/eai/domains/evidence/common.py (auditor, security_officer, tenant_admin) plus tenant_admin, agent_operator and developer. platform_admin passes every role check.

Typical tasks​

Find why a run failed​

  1. Filter the failed runs. The list shows every run of the tenant, newest first. Choose Failed in State, type the agent name in Agent, then click Filter. Expected result: only the failed runs of this agent remain. If it fails: invalid_request (400) means the state value is not a run state; pick one in the list.
  2. Open the run. The run page holds the full history. Click the row. Expected result: the timeline, the budgets and the checkpoints show. If it fails: run_not_found (404) means the run id is unknown in the current tenant.
  3. Read the failing step. Each step carries its state, attempt, tokens and cost. Find the step marked Failed in Execution timeline, then read errors in Execution Contract. Expected result: you see the error code (for example budget_exceeded). If it fails: when No step yet shows, the run failed before its first step; check the agent and its budgets.

Resume a suspended or failed run​

  1. Check the agent. A run resumes only when its agent is active. Open the agent from the Registry. Expected result: the status Active. If it fails: resume the agent first (approval required).
  2. Resume the run. Without a choice of strategy, the run restarts from its last checkpoint. Click Resume on the run page. Expected result: the toast Done and the state Running. If it fails: no_checkpoint (409) means the run has no checkpoint; run_not_resumable (409) means it stopped on budget_exceeded, max_steps_exceeded, killed or approval_rejected and needs a new run.
  3. Follow it. The page follows the live events. Watch the timeline. Expected result: new steps appear without reloading the page. If it fails: reload the page to read the run again.

Prove which configuration a run used​

  1. Open the evidence. Auditors need the exact versions behind a run. In the row menu of the run, click Configuration evidence. Expected result: a side panel shows the configuration as JSON. If it fails: forbidden (403) means your role is not among the evidence readers.
  2. Replay the run. The replay puts the steps, checkpoints, run events and audit events in one ordered timeline. Open the run and click Replay. Expected result: the Replay section shows the timeline. If it fails: forbidden means you need auditor, security_officer or an operations role.

Troubleshooting​

SymptomCauseFix
invalid_transition (409): "A run cannot go from ... to ..."The run is not in a state that allows the action (for example Resume on a running run, Cancel on a finished run).Check the state badge; only suspended, failed, timed out or waiting for input runs can resume.
agent_not_active (409) on ResumeThe agent of the run is suspended or killed.Resume the agent in the Registry, then the run.
no_checkpoint (409)The run has no checkpoint to resume from.Start a new run from the agent.
run_not_resumable (409)The run stopped on a budget, step limit, kill or rejected approval.Start a new run, with a higher budget when needed.
forbidden (403) with required_rolesYour roles do not allow the action.Ask for one of the roles listed in the error.
No budget recorded for this run.The run was started without budgets and the agent declares none.Set spec.budgets in the agent manifest or Max cost (EUR) when you start the run.
State Waiting approval that does not moveA step waits for a human decision.Decide the request in the Approvals inbox.