> ## Documentation Index
> Fetch the complete documentation index at: https://docs.encord.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Running Agents

There are two ways to run Agents in Encord:

* **In the Label Editor**: The Agent is triggered on demand by the Tasker while annotating or reviewing a task.
* **From your Workflow**: The Agent is triggered on tasks that pass through the Workflow node.

## In the Label Editor

All agents created via the Agents Catalog (built-in and custom) are triggered in the same way from the Label Editor:

1. Open the data item in the Label Editor.
2. Right-click in the editor canvas, choose **Trigger agent**, and select the agent you want to run.

<div class="flex justify-center">
  <img src="https://storage.googleapis.com/docs-media.encord.com/static/img/editor-agent-right-click.png" />
</div>

## In the Workflow

Agents can be added as a Workflow node when creating or editing a Workflow. When the Workflow runs, the Agent is triggered for all tasks that pass through that node.

1. Drag the **Agent** node in the Workflow editor onto the canvas and connect it to the desired nodes.

<div class="flex justify-center">
  <img src="https://storage.googleapis.com/docs-media.encord.com/static/img/workflow-agents-1.png" />
</div>

2. Click the **Agent** node.
3. Click the **+** to add a new Agent, or the dropdown to select an existing enabled Agent.

<div class="flex justify-center">
  <img src="https://storage.googleapis.com/docs-media.encord.com/static/img/workflow-agents-2.png" width="300" />
</div>

4. Click **Run** next to a task to run the Agent on a specific task to verify the output is as expected.

5. Click **Go live** to automatically run the Agent on tasks that pass through this node in the Workflow.

<Info>
  Agent activity can be monitored in the **Analytics** dashboard. See [Analytics for Agents](/platform-documentation/Annotate/annotate-projects/annotate-project-analytics#agents) for details.
</Info>

<div class="flex justify-center">
  <img src="https://storage.googleapis.com/docs-media.encord.com/static/img/workflow-agents-3.png" />
</div>

<Note>
  If you do not have access to the Ontology required by an Agent, you see an error message with an option to join the Ontology, if you're an Org Admin.
</Note>

### Agent Task Management

When viewing an Agent stage, the Queue displays additional controls and status information for Workflow agents.

**Agent Status Banner**

For Agent stages, a status banner appears above the task list showing the agent name and icon (click to view detailed agent configuration), a status indicator showing whether the agent is Live (green) or Paused (orange), and control buttons that Admins and Team Managers can use to pause/resume agents or view agent settings.

**Agent Controls**

<Note>Only Workspace and Project Admins and Team Managers can control agent execution.</Note>

| Action                | How                                                                    |
| --------------------- | ---------------------------------------------------------------------- |
| Pause agent           | Click **Pause** to stop automatic processing                           |
| Resume agent          | Click **Go live** to resume automatic processing                       |
| Manual task execution | Navigate to paused agent stage → find **Pending** task → click **Run** |
| Retry failed task     | Find **Failed** task → click **Retry**                                 |

<Tip>Use manual execution when testing agent configurations or troubleshooting specific data units before resuming live processing.</Tip>

**Agent Execution Status**

For Projects using Agents in their Workflow, tasks display execution status badges showing the current state of automated processing:

| Status     | Description                                                               |
| ---------- | ------------------------------------------------------------------------- |
| Pending    | The agent execution is queued and waiting to start.                       |
| Dispatched | The agent execution has been assigned to a worker.                        |
| Running    | The agent is currently processing the task.                               |
| Succeeded  | The agent execution completed successfully.                               |
| Failed     | The agent execution encountered an error and failed to complete.          |
| Timed out  | The agent execution exceeded the maximum allowed time and was terminated. |
| Canceled   | The agent execution was manually canceled before completion.              |

**Retry Failed Tasks**

You can retry tasks that failed or timed out by selecting one or more affected tasks in the Queue, then clicking Retry failed to re-run the agent on those tasks. The system will attempt to execute the Agent again on the selected tasks.

<Note>The Retry failed button is only available for Agent stages with catalog agents and only appears when you have selected tasks that failed or timed out.</Note>

**Moving Agent Tasks**

When moving agent tasks to the next stage, the system skips tasks that are currently running or dispatched (they remain in the current stage), only moving tasks that are not actively being processed. A confirmation dialog will show how many tasks are moved and how many are skipped.

<Warning>Tasks that are currently running or dispatched cannot be moved and remain in their current stage until execution completes.</Warning>

## Creating Projects with Agent Stages

When creating a new Project that includes an Agent stage, you must be a member of the Agent's associated Ontology. If you are not a member of the required Ontology, the **Create project with agent stage** button is disabled.

<Note>If you see a disabled **Create project with agent stage** button with a tooltip message, you need to join the Agent's ontology before you can create a project using that Agent.</Note>

To resolve this:

1. Contact your Workspace Admin or Ontology owner to request access to the required Ontology.
2. Once you have been added as a member of the Ontology, the **Create project with agent stage** button becomes available.
3. Create the Project with the Agent stage included.