Agent runs

An agent does not run all the time. It works in runs: one run is one session of one agent on one task, from waking up to stopping (submitting, asking, waiting or failing). Every run is recorded in Polarion as an Agent Run (aiRun) work item.

What starts a run

flowchart LR
  TR["<b>Triggers</b><br/><small>assignment · reply · rejection<br/>delegation · teammate · approval<br/>nudge · budget raised · manual</small>"]:::you --> W["<b>Watcher</b><br/><small>one run per task at a time</small>"]:::run
  W --> RUN["<b>Run</b><br/><small>instructions + task prompt</small>"]:::run
  RUN --> O1["<b>submitted</b>"]:::ok
  RUN --> O2["<b>asked human</b>"]:::you
  RUN --> O3["<b>waiting for approval</b>"]:::you
  RUN --> O4["<b>budget stopped · failed</b>"]:::bad
  RUN --> REC["<b>Agent Run item</b><br/><small>cost · ledger · transcript</small>"]:::pol
  classDef pol fill:#dcecec,stroke:#0d6e6e,stroke-width:1.2px,color:#12302f
  classDef run fill:#ece5fb,stroke:#7c3aed,stroke-width:1.2px,color:#2b1d4f
  classDef ext fill:#e3ebfb,stroke:#2563eb,stroke-width:1.2px,color:#16264a
  classDef you fill:#fdf0d8,stroke:#b7791f,stroke-width:1.2px,color:#4a3210
  classDef ok fill:#e3f2e7,stroke:#1f7a3d,stroke-width:1.2px,color:#143d22
  classDef bad fill:#fbe4e2,stroke:#b3261e,stroke-width:1.2px,color:#4d1612
  classDef mute fill:#f1f4f6,stroke:#8a96a3,stroke-width:1.2px,color:#2a3440

The runner’s watcher polls Polarion every few seconds (5 by default). It looks at tasks assigned to bot users that have an active engagement in the project, and ignores tasks that are done, verified, rejected or awaiting_approval. Runs are serialized: one run per task at a time, and one run per agent at a time.

Trigger	When
assignment	A task is assigned to a hired agent and the watcher has not seen it before. A delegated sub-task with an “after” dependency waits until that sub-task is done or verified.
human_reply	A person commented on the task after the agent’s last action (an answer, a hint). The run goes to the agent that asked.
rejection	The task was sent back (status reopened).
delegation_done	A sub-task the agent delegated reached awaiting_approval, or all of its sub-tasks are done.
teammate_question	A teammate working on a delegated sub-task asked a question; the delegating agent answers first.
teammate_answer	The delegating agent answered; the teammate continues.
approval	The supervisor decided on held changes and nothing is pending for the task any more.
nudge	The previous run ended without submitting, asking or waiting (see Stalls).
budget_raised	The supervisor raised a budget that had run out; stopped tasks continue.
manual	You pressed “Wake now” in the task panel.

The task panel also wakes the agent right away when you answer or send back, so you don’t wait for the next poll.

How the instructions are built

flowchart LR
  P["<b>Persona</b>"]:::run --> I["<b>Instructions</b><br/><small>same for every run</small>"]:::run
  SK["<b>Approved skills</b>"]:::run --> I
  PI["<b>Project instructions</b><br/><small>engagement</small>"]:::pol --> I
  ME["<b>Approved memories</b><br/><small>for this agent</small>"]:::pol --> I
  TE["<b>Supervisor · team</b><br/><small>connected systems</small>"]:::pol --> I
  RU["<b>Platform rules</b>"]:::mute --> I
  I --> RUN((("<b>Run</b>"))):::run
  TP["<b>Task prompt</b><br/><small>description · links · comments · trigger</small>"]:::you --> RUN
  classDef pol fill:#dcecec,stroke:#0d6e6e,stroke-width:1.2px,color:#12302f
  classDef run fill:#ece5fb,stroke:#7c3aed,stroke-width:1.2px,color:#2b1d4f
  classDef ext fill:#e3ebfb,stroke:#2563eb,stroke-width:1.2px,color:#16264a
  classDef you fill:#fdf0d8,stroke:#b7791f,stroke-width:1.2px,color:#4a3210
  classDef ok fill:#e3f2e7,stroke:#1f7a3d,stroke-width:1.2px,color:#143d22
  classDef bad fill:#fbe4e2,stroke:#b3261e,stroke-width:1.2px,color:#4d1612
  classDef mute fill:#f1f4f6,stroke:#8a96a3,stroke-width:1.2px,color:#2a3440

The instructions (system prompt) are the same for every run of an agent in a project. The Agent brain view shows the exact text, built by the same code. In order:

1. Persona: the agent’s description from the Agent Pool.
2. Identity: name, role, that it works only through tools and is audited, and today’s date.
3. Skills: the instructions of every approved skill linked with ai_has_skill.
4. Project instructions: from the engagement.
5. Lessons from your supervisor: the active project memories for this agent (see Memory).
6. Supervisor: who answers questions and approves results.
7. Team: the other hired agents with their role, skills and connected systems.
8. Connected systems: each granted connection with its scope, how many tools are read, need approval or are blocked, and the project notes. A connection without a required scope is listed as not set up, with how to ask for one.
9. Rules: how to work (read before acting, avoid duplicates, put items into documents, link artifacts, never write approval markers into item text, ask instead of inventing values, finish with a submission or a question, never hand work back to the supervisor).

Sandbox agents also get a workspace note: the sandbox, that all systems are reached through the gateway, which websites they may read (or that there is no internet), and how git works for them.

The task prompt

Each run gets a prompt built from the task as it is now:

• the trigger,
• the task’s id, status, title and description,
• its links and its delegated sub-tasks with status and assignee,
• the whole comment thread, oldest first (each comment shortened to 800 characters),
• held changes that still wait for the supervisor (“don’t ask again”),
• a hint for the trigger, e.g. “the supervisor sent your result back: address exactly the feedback”.

Harnesses

Harness	Where it runs	Models	Notes
builtin	In the runner	Anthropic, OpenAI, Google	Pydantic AI loop. Tools through the MCP gateway. Hard budget stop mid-run.
claude_code	Claude Code in the task’s sandbox	Anthropic	Shell, files and git in /workspace. Session resumed on the next run. Budget passed as a cost cap.
codex	Codex CLI in the task’s sandbox	OpenAI	Same sandbox and gateway. Thread resumed on the next run. No in-run cost cap.

In every harness the agent reaches Polarion and connected systems only through the MCP gateway, with a run token that is valid for this run only. A sandbox harness talks to the gateway through the sandbox entrance. See Sandboxes.

Runs are bounded by a step limit (40 model requests by default) and, in a sandbox, by a 45-minute time limit.

Outcomes

Outcome	Meaning
submitted	The agent submitted its result; the task is awaiting_approval
asked_human	The agent asked questions; the task is waiting_input
waiting_approval	A write was held for approval; the task is waiting_input
done	The run ended without one of the above (e.g. it waits for sub-tasks, or it answered a teammate)
failed	An error, or the step limit was reached
budget_stopped	The engagement’s budget ran out during the run

What a run records

When a run ends, the runner (with its admin account) creates the Agent Run item:

• Fields: agent, provider, model, trigger, outcome, tokens in and out, cost, steps, duration, skills in effect, memories used.
• Ledger: every artifact the run touched, as JSON and as a readable table. Actions are read, searched, created, changed, commented, delegated, requested (held for approval, with the approval id) and blocked. Entries cover Polarion items, documents and queries, objects in connected systems (by URL and title), repositories and branches, and web pages read in a sandbox.
• Gateway calls: tool, decision, result, duration and a short summary of the arguments.
• Sandbox facts (sandbox runs): sandbox id, image, harness, commands, web pages, allowed sites, budget cap.
• Transcript: transcript.html (readable) and transcript.json (raw model messages or harness events).
• Links: ai_run_of → task; created items ai_created_by_run → run; changed items ai_modified_by_run → run.

The run’s cost is added to the engagement’s spent. The task panel’s run trace and the AI Reports are built from these records.

Delegation

An agent with the delegate tool can hand work to a teammate hired in the same project. delegate creates a sub-task (AI-marked, parent → the current task, assigned to the teammate). With “after”, it gets a depends_on link and starts only when that sub-task is done.

• The delegating agent reviews the result (review_subtask: approve, or send back with feedback) and is woken for that.
• Questions on a sub-task go to the delegating agent first. It answers (answer_teammate) or asks the supervisor. Questions about a connection’s scope always go to the supervisor.
• A delegated sub-task is always finished with submit_for_approval, which wakes the delegator.
• The delegating agent cannot submit its own task while sub-tasks are open.

Limits keep agents from looping:

Limit	Value
Follow-up sub-tasks (new sub-tasks after the initial planning)	2 since the supervisor’s last comment on the task
Sending the same sub-task back	2 times; then the delegator must approve it or ask the supervisor
The same sub-task twice	Refused if an open sub-task with the same title and assignee exists

Only the top-level task is approved by a person. Sub-tasks are approved by the agent that delegated them.

Stalls

A run can end without submitting, asking or waiting for anything, e.g. after only posting a comment. Nothing would wake the agent again. The watcher detects this (task still open, no open sub-tasks) and:

1. Starts one nudge run that tells the agent to finish.
2. If the nudge run stalls too, posts “Agent stopped — needs you” on the task and sets it to waiting_input, so it shows up for the supervisor. A comment from you wakes the agent again.

Budgets

Budgets are per engagement, in USD, and they are hard caps:

• Before a run: no run starts when spent has reached budget.
• Built-in harness: the run stops mid-run when its cost reaches the remaining budget; the cost so far is recorded and the outcome is budget_stopped.
• Claude Code: the remaining budget is passed as Claude Code’s maximum cost for the run.
• Codex: checked before each run only; the step limit bounds a run.
• Chat: a chat turn does not start when the budget is used up; its cost is added to spent.

Raising the budget on the Team page wakes the agent’s stopped tasks with budget_raised. Costs are computed from token usage and a price table in the runner. See Budgets.