> ## Documentation Index > Fetch the complete documentation index at: https://cogno.studio/docs/llms.txt > Use this file to discover all available pages before exploring further. # Run an agent on a task > Have a Cogno agent spec or implement a task — it drafts the work, opens a pull request, and reports back. An **agent** is an AI worker that runs a task on your behalf. Instead of doing the work yourself, you hand a task to an agent: it can **spec** the task (draft a specification into the description) or **implement** it (carry out the work and open a pull request), then report back on the task. This page shows how to start an agent run from a task and how to read a run's status. The work runs on a **worker** — a machine connected to your workspace. You monitor workers and every run's history in **Settings → Worker Hub**. ## 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. Open the task you want an agent to work on so its detail canvas is showing. 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**. An offline environment can still be selected. The run stays queued until a matching worker for that environment comes online. 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. 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 | Action | What it does | What it delivers | | ------------- | ---------------------------------------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------- | | **Spec** | Drafts a specification for the task — the agent investigates the repo and returns a structured spec. | The spec is folded into the task **description**, with a report of candidate plans and any open questions. | | **Implement** | Carries out the work described by the task. | A GitHub **pull request**, reported back on the task as an **✅ Implementation delivered** comment with the PR link(s). | 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: | Button | When it appears | What it does | | ----------------- | -------------------------------------------------------- | ---------------------------------------------------------------------------------- | | **View PR** | Always, when the run opened a pull request. | Opens the pull request on GitHub. | | **Merge PR** | Only when the workspace's GitHub App can reach the repo. | Merges the pull request. GitHub branch protection and CI requirements still apply. | | **Preview** | When the change ships a preview deployment. | Opens the preview URL for the branch. | | **Mark complete** | Always. | Sets the task to completed. | | **Archive** | Always. | Archives the task and hides it from the task lists. | **Merge PR** and **Archive** ask for confirmation before running, because both are hard to undo. Merging still respects the repository's branch protection and CI requirements. ## 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 | Choice | Routing behavior | | ---------------------- | ------------------------------------------------------------------------------------------------------------------------------------- | | **Automatic routing** | Uses the task assignee and the workspace's available workers. | | Registered environment | Routes to the selected environment's owner, machine, and directory. This explicit choice takes precedence over task-assignee 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. | State | Pill label | Meaning | | --------- | ------------- | --------------------------------------------------------- | | queued | **Pending** | Enqueued, waiting for a worker to pick it up. | | claimed | **Claimed** | A worker has claimed the run but not started it. | | working | **Running** | The worker is actively doing the work. | | completed | **Completed** | The run finished successfully and reported its result. | | failed | **Failed** | The run stopped with an error, shown on the run. | | cancelled | **Cancelled** | The run was cancelled before it reached a terminal state. | **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 | Limit | Value | | --------------------------------- | ------------------------------------------- | | Concurrent agent runs per task | One at a time. | | Spec candidate plans | Up to 3 (one may be recommended). | | Spec open questions | Up to 10, each with up to 4 answer options. | | Screenshot attachments from a run | PNG, up to 25 MB each. | | Worker liveness window | Stale after 2 minutes without a heartbeat. | ## Troubleshooting | Symptom | Likely cause | Fix | | --------------------------------------------------------- | --------------------------------------------------------------------- | ----------------------------------------------------------------------------------------------------- | | The run stays **Pending** and never starts. | No eligible worker is online, or the selected environment is offline. | Bring a matching worker online; the queued run starts automatically. Check **Settings → Worker Hub**. | | The start control is disabled. | A run is already in flight for this task. | Wait for the current run to finish — only one agent run happens per task at a time. | | The implement report has **View PR** but no **Merge PR**. | The workspace's GitHub App can't reach the repo. | Connect or re-authorize the GitHub App for that repository, then merge on GitHub. | | The run shows **Failed**. | The run stopped with an error. | Open the run in Worker Hub to read the **Error**, then start a new run. | For anything not listed here, see [Troubleshooting](/docs/troubleshooting). ## Related docs * [Concepts](/docs/concepts) — how agents fit the events → agent → workers loop. * [Tasks](/docs/tasks) — create and manage the tasks you hand to an agent. * [Getting started with Cogno](/docs/getting-started) — set up the loop end to end.