Prerequisites
- A Cogno workspace with a task to work on.
- At least one worker online in the workspace. If none is online when you start a run, the run is queued and starts once a worker comes online.
- For an implement run that opens a pull request, a connected GitHub App so the run can push a branch and open the PR.
Start an agent run
Open a task, then start the run from the task detail.1
Open the task
Open the task you want an agent to work on so its detail canvas is showing.
2
Choose the worker environment
Select Assign to Cogno, then choose where the run should go:
- Automatic routing uses the task assignee and available workers.
- A registered environment routes the run to that machine and directory. Each environment shows whether its worker is Online or Offline.
3
Start the work
Choose Automatic routing or an environment to hand the task to an agent. The
button shows Assigning… while the request is being created. Only one agent
run happens per task at a time, so the control is disabled while another run is
pending, claimed, or running.
4
Wait for the run to finish
The run moves through its states (queued → claimed → working → completed or
failed). When it finishes, the agent posts a report back on the task. An
implement run that produced a pull request posts an ✅ Implementation
delivered report with a View PR link.
A task can also be spec’d or implemented directly from the agent action controls on
the task detail. Those actions map to the same run lifecycle described below — a
Spec run drafts the specification into the task description, and an
Implement run carries the work out and opens a pull request.
What each action does
A spec run returns candidate plans (up to three, one may be recommended) and up to
ten open questions for the team to answer, along with a confidence grade.
Read a run’s report
When an implement run completes, the agent posts a report comment on the task headed ✅ Implementation delivered. Depending on the result, the report carries these actions:Track runs in Worker Hub
Every agent run is recorded under Settings → Worker Hub, on the History tab. The list shows the 50 most recent work items dispatched to your workers, newest first, each with its status, the worker that ran it, timing, and — when the run opened a pull request — a View PR link. When there are no runs yet you’ll see No agent work yet. Select a run to open its detail, which shows its Intent, Type, Worker, Owner, Task, Routing reason, timing (Created, Claimed, Started, Completed, Duration), the Summary, and the Activity log.Worker Hub auto-refreshes every 10 seconds. A worker that stops reporting for two
minutes shows as stale, then offline.
Reference
Worker environment routing
Registered environments come from Settings → Worker Hub. If Cogno cannot load
them, the action shows Worker environments could not be loaded.
Agent run states
An agent run moves through these states. The Worker Hub history shows the state as a labelled pill.
Pending, Claimed, and Running are the non-terminal states — a run in any
of them can be cancelled from its row’s More actions menu. Completed,
Failed, and Cancelled are terminal.
Limits
Troubleshooting
For anything not listed here, see Troubleshooting.
Related docs
- Concepts — how agents fit the events → agent → workers loop.
- Tasks — create and manage the tasks you hand to an agent.
- Getting started with Cogno — set up the loop end to end.