> For the complete documentation index, see [llms.txt](https://docs.unitlab.ai/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.unitlab.ai/documentation/workflows/agent-stage.md).

# Agent stage

Hand each task to a service you host: it reads the item, saves its annotations, then completes the task.

![An Agent stage in the workflow editor: the stage panel holds the service's HTTPS URL, an optional signing secret and Test connection](https://292810646-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FGjVLUz4wthGkGlRKM6rM%2Fuploads%2FfSB5MoE7tpLsevb6eq2F%2Fagent-stage-editor.png?alt=media)

An **Agent** stage hands each task to a service you host, for example to refine the outlines a model stage produced, check or correct annotations with your own rules, or sync work with another system. Unitlab sends your service one event per task. The event names the task only; your service reads the item, saves its new annotations, then completes the task, which moves it along the stage's one route.

## How a run works

1. A task enters the Agent stage, and Unitlab sends your service an event that names the task and its run.
2. Your service answers at once with a 2xx and does the work in the background.
3. It reads every item of the task with the SDK: one annotation document per item, with the item's media link.
4. It saves each changed item. A save replaces the item's annotations whole: objects missing from the document are removed.
5. It completes the run, and the task moves on. If something goes wrong, it fails the run with a reason instead.

People can open and edit the item while it is in the Agent stage. A save by your service replaces the annotations, including edits made after the service read them.

## Add an Agent stage

1. Add an **Agent** stage to the workflow and connect its one output to the next stage.
2. Set **HTTPS URL** to your service's public HTTPS address.
3. Optionally set a **Signing secret**. Every event is then signed with Standard Webhooks, so your service can check that it came from Unitlab. The secret is never shown again after saving.
4. Click **Test connection**. A new Agent stage, or one whose URL or secret changed, can be saved only after a passing test.
5. Use **Save & Apply**.

{% hint style="warning" %}
Without a signing secret, events are unsigned: anyone who knows the address can send an event that names a task. Use a secret whenever the address is reachable by others.
{% endhint %}

## Follow runs in the Task Queue

The Agent stage queue shows each task's run: sending, retrying, waiting for your service, or failed, with the try count, the last error, the next try and the result deadline.

* **Delivery** is tried up to 5 times when your service does not answer in time, cannot be reached, or answers with a 5xx. Any other error answer fails the run.
* **A failed run** stays in the Agent stage with its reason until a member with the **Manage data** permission clicks **Retry**, which sends the task again as a new run.
* **A Review rejection** whose Rejected route points back to the Agent stage sends the task to your service again as a new run.
* **A result deadline** of 7 days: a run your service does not complete in time fails and waits for Retry.

## Stop, Retry and moving tasks out

Members with the **Manage data** permission can act on runs from the Agent stage queue (**Queues** → the Agent stage):

* **Stop** is shown on a task while its run is **Sending to your service** or **Waiting for your service's result**. Stopping ends the run as failed with the reason "Stopped by a manager". Your service is not notified; if it answers later, its result is refused.
* **Retry** is shown on a failed run: delivery failed, your service reported a failure, no result came within 7 days, or the run was stopped. It starts a new run with a new run ID, fresh delivery tries and a new result deadline. A result for the old run is refused.
* **Moving tasks out**: select tasks in the Agent stage, including ones still waiting for a result, and move them to another stage with **Bulk actions**. Once a task has left the Agent stage, your service can no longer save its annotations or send its result: both are refused with an error and nothing is saved. Moving the task back into an Agent stage starts a new run, so a result for the old run stays refused.

## What your service can save

| Format                             | For                            | Notes                                                                                                                                                                                                                                   |
| ---------------------------------- | ------------------------------ | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| Unitlab annotation document (UUEF) | Every data type                | The same per-item JSON a release exports. Video and medical tracks save their keyframes.                                                                                                                                                |
| GeoJSON (geospatial models)        | Geospatial and pathology items | The FeatureCollection a geospatial model returns, naming project classes. Coordinates in lon/lat, the raster's own map units, or pixels.                                                                                                |
| Prediction format (image models)   | Images                         | The predictions an image model connected under **My AI Models** sends back to Unitlab, described in [Bring your own Models](https://docs.unitlab.ai/documentation/auto-labeling/bring-your-own-models.md#representative-image-request). |

The [Annotation JSON reference](https://docs.unitlab.ai/api-sdk-cli/apis/annotation-json-reference) describes all three.

## What your service must do

* Check the event's signature when the stage has a secret, and answer 2xx at once.
* Read the task's items, change what it needs, and save each changed item.
* Complete the run, or fail it with a short reason.
* Treat repeated events for the same run as one: a delivery can arrive more than once.
* Stop working on a task when a save or result is refused because the run was stopped or the task was moved out. There is nothing to clean up.

See [Pattern: Workflow worker](https://docs.unitlab.ai/api-sdk-cli/sdks/pattern-workflow-worker) for a complete example with the Python SDK.

## Next steps

* [Stages and routes](https://docs.unitlab.ai/documentation/workflows/stages-and-routes.md)
* [Model stages](https://docs.unitlab.ai/documentation/workflows/model-stages.md)
* [Change a live workflow](https://docs.unitlab.ai/documentation/workflows/change-a-live-workflow.md)
