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.

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.

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

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.

Agent activity can be monitored in the Analytics dashboard. See Analytics for Agents for details.

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.

Decision Pathways

Some Agents are built on templates that define a fixed set of possible decisions — for example, accept, reject, and needs_review. When you select one of these Agents in the Workflow builder, Encord automatically populates the Agent node with one named pathway per decision, replacing the default single pathway.

How decision pathways work:

• When you select a decision-routing Agent from the dropdown in the Agent node panel, the node’s pathways update automatically to reflect the decisions defined by the Agent’s template.
• A Decision pathways section appears in the Agent panel, listing each pathway name and its ID.
• Each pathway acts as a separate exit handle on the Agent node that you can connect to a downstream Workflow stage.
• If you switch to a different Agent that does not use decision routing, the pathways reset to a single default pathway.

Use the pathway IDs listed in the Decision pathways panel to identify and wire each exit to the correct downstream node — for example, connecting accept to a Review stage and reject to Complete.

To connect decision pathways to downstream nodes:

1. Add an Agent node to the Workflow

   Drag the Agent node onto the Workflow canvas and connect it to the desired upstream node.

2. Select a decision-routing Agent

   Click the Agent node to open the panel, then select a decision-routing Agent from the dropdown. The node updates to display one exit handle per decision.

3. Review the Decision pathways panel

   In the Decision pathways section of the panel, review the list of named pathways and their IDs.

4. Connect each pathway to a downstream node

   Drag each named pathway handle on the Agent node to the appropriate downstream Workflow stage.

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

Only Workspace and Project Admins and Team Managers can control agent execution.

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

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

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.

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.

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.

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

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.

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.

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.

Repeatable Ontology Feature Requirements

Some agent templates support repeatable ontology feature requirements. A repeatable requirement allows you to select multiple ontology features for a single role — for example, selecting several source object classes for an agent that merges object classes.

Identifying repeatable requirements

When configuring an agent whose template includes a repeatable requirement, the feature selector for that role displays a multi-select tree picker instead of the standard single-select dropdown. You can search and select multiple features from your ontology within the same field.

Selection validation

Repeatable requirements enforce minimum and maximum selection counts:

• Minimum selections: You must select at least the required number of features before you can submit the agent configuration. If you have not met the minimum, the form displays a validation message such as “Please select at least N features.”
• Maximum selections: When a maximum is configured, the picker prevents additional selections once you reach the limit.

The minimum and maximum counts are defined by the agent template. If no maximum is set, you can select as many eligible features as your ontology contains.

Ontology compatibility

When selecting an ontology during agent creation, Encord automatically filters out ontologies that do not contain enough eligible features to satisfy the minimum count for any repeatable requirement. Only compatible ontologies appear in the selector.

Viewing repeatable features in the agent detail

In the agent detail view, multiple features selected for a repeatable requirement are displayed grouped under a single role label. For example, if you selected three source object classes, the detail view shows:

Source Object Classes: [ClassA] [ClassB] [ClassC]

This grouped display replaces the previous behavior of showing separate rows with indexed suffixes.