Giving an agent work

An agent is hired once and then used every day. This is the every-day half: how to hand it a task, what it actually reads, how to watch it, and what comes back.

Hiring one is Hiring an agent, and giving it a machine to run on is Connecting a runtime. Both are done once. Nothing on this page needs an administrator.

Two ways to hand it over

Both queue a run immediately. Assigning to a person queues nothing, which is the whole difference between the two kinds of assignee: a person decides when to start.

An agent picks up its next run in about three seconds. If it has worked on that issue before it resumes the same session, so it still knows what it did last time.

There is a third way, on the dashboard: Idle machines offers pool issues that fit an agent with time left in its day, and Hand over assigns one. See Reports for where the capacity figure comes from.

What the agent actually reads

This is the part worth knowing before anything else, because it is not what the screen implies.

The agent is started with one brief, assembled in this order:

1. Where it is — the run directory, and which repositories are checked out in it
2. Agent context — one paragraph for the whole workspace, from Admin → Workspace
3. Instructions — the agent's own, from its page
4. ## ACME-42 — The title (priority: high)
5. The description
6. The acceptance criteria, as a list

Plus any skills that apply, written into the run directory as files.

The comment thread is not in it. Not the comment that mentioned the agent, and not any comment before it.

So this does what you expect:

Description: The token is refreshed on every request but never stored, so the next request refreshes it again. Store it in the session and read it back.

And this does not:

@Freya — also check whether the same thing happens on the webhook path.

The mention starts a run. The words after it are read by people and not by the agent, which means the run goes off to do whatever the description already said. If something matters, put it in the description and then mention the agent, or edit the description and use Queue another.

Writing a task an agent can finish

Everything above has one consequence: the issue is the brief. What follows is what that looks like in practice.

Say what done looks like. Acceptance criteria are sent as their own list, and they are the only part of an issue shaped like a finish line. Three specific ones beat a paragraph of prose.

Name the file, the route, the command. An agent has the repository checked out and no idea which of four hundred directories you meant. app/Support/Timesheet.php costs you four words and saves it ten minutes of looking.

One issue, one outcome. A run ends when the CLI ends. An issue that asks for three unrelated things gets one attempt at all three.

Don't hand it an epic. Nothing stops you, and nothing good happens: an epic is a container for other issues, so the agent receives a title, no work and no way to finish. Assign the issues inside it.

Give it a size. An unestimated issue is never offered by Hand over, is counted apart in every report, and cannot be planned around — see Reports.

Watching it work

While a run is in flight the issue shows Current run with the output as it arrives, pushed over the websocket rather than polled. Above it sit the artifacts the runs on this issue produced: the delivery is the answer and the output is the working, so the answer reads first.

A run passes through these:

Queued means waiting for a slot, not waiting for a machine. Each agent has a concurrency limit. At its limit it is passed over rather than blocking the queue, so other agents keep working.

Queue another starts a fresh run on the same issue without changing the assignee. Use it after editing the description, which is the ordinary way to say "not like that, like this".

Stopping one

There is no stop button, and the honest version of what is available is short:

• A run still queued stops if you withdraw the comment that mentioned the agent. The run had not started, so nothing is lost.
• A run already going finishes. It also ends if the issue is deleted, or if the machine it is on stops — the daemon hands its tasks back and they are requeued.

That is a gap rather than a design. Stopping a run in flight is on the list.

What comes back

A comment. The agent posts its summary in the thread, as itself, and it reaches everybody following the issue the way any comment does — there is no digest and no separate setting for agent comments. See Inbox and Email.

Time. The run's duration is added to the issue's spent time, so a machine's hours sit beside a person's in the time report and on the timesheet. An agent's hours are the one kind nobody can edit: the run is in the timeline with its own duration, and correcting the figure would let the report disagree with the history it came from.

Anything it delivered — a pull request, a file, a branch. See Delivering work and GitHub.

A line on the activity tab, for the assignment, the mention and the run.

When it fails

A failed run says what happened in the thread rather than only in a status. Two kinds:

It tried and could not. The CLI exited with an error, and what it printed is in the run output. Read it, fix the brief, Queue another.

It never really started. Not logged in is the commonest: the CLI is signed in as a different user than the daemon runs as. That is a machine problem, not an issue problem — Connecting a runtime lists the symptoms and their causes.

A machine that disappears mid-run — a closed laptop, a restart — does not lose the work. The runtime is marked offline within 45 seconds and the task is requeued once its lease expires, so another machine picks it up.

Work that starts itself

An autopilot opens an issue and assigns it to an agent, on a trigger. Admin → Autopilots.

It deliberately opens an issue rather than starting a run directly. Automated work then lands on the same board, in the same thread and under the same permissions as work a person assigned, and nobody has to learn a second place to look for it.

The issue it opens comes from a template, and the template takes placeholders — in the title and the description both:

{{ date }} {{ time }} {{ datetime }} {{ weekday }} {{ week }} {{ month }} {{ year }}

Dates resolve in the autopilot's own timezone, which is why the schedule asks for one. For a webhook, anything in what was posted is available under payload, reached with dot notation: {{ payload.repository.name }}.

A placeholder with nothing behind it is left as it is rather than blanked. A board full of {{ payload.title }} tells you the payload changed shape; a board with gaps tells you nothing.

Teaching it

Four places, from narrowest to widest:

Agent context is prepended to every agent's instructions — "Always run the test suite before finishing. Prefer small pull requests." It goes to the CLI verbatim.

Allowed repositories is on the same page, one URL per line. A task may clone those and nothing else. The machine supplies its own git credentials, so no tokens belong in the URL.

Not there yet

• A run cannot be stopped once it starts. Withdrawing the comment stops one still queued; after that it runs to its end.
• Comments are not sent to the agent. Only the issue is. A mention is a start button.
• An epic can be assigned to an agent and nothing warns you. It will not go well.
• No way to ask for a description as Markdown over the API. Agents read and write Markdown well, and an issue's description arrives as HTML — see the API reference.