Runner
classes are the core components for building task agents in Encord.
They provide a simple interface for defining agent logic and moving tasks through the Encord project workflows.
The Runner
s manage the execution of agent logic on tasks within specific workflow stages.
They are responsible for:
Runner
s and how to use them.
start
, agent
, and complete
. The Runner
objects from encord_agents.tasks.runner
is used to define the logic for agent stages (the purple nodes in the workflow).
In this example, the Runner
is responsible for implementing the logic for the Agent 1
stage.
Workflow Specification
@runner.stage
decorator connects your functions to specific stages in your Encord workflow. For the workflow above, the logic for the Agent 1
stage can be defined in the following manner:
UUID
.
If None
is returned, the task remains in its current stage and will be reprocessed during the next execution of that stage.
You can also define multiple stages in a single runner:
Runner
used. For example, if a Runner
is configured with two stages:
=== “Runner”
Runner
executes the tasks in the order in which the stages were defined in the runner.
That is, the tasks are processed in stage_1
first and in stage_2
next.
=== “QueueRunner”
QueueRunner
gives you control over the task queues for each stage.
Please refer to the QueueRunner documentation for more information.
@runner.stage(...)
, you can include the label_row_metadata_include_args: LabelRowMetadataIncludeArgs
argument. This argument passes directly to the Encord Project’s list_label_rows_v2
method, enabling you to read client metadata associated with a task. If you need to update metadata, use the dep_storage_item
dependency.
Here is an example:
task
, lr
, twin
, and frames
variables are automatically injected with their respective dependencies. This provides the flexibility to inject only necessary dependencies, allowing you to focus solely on your agent’s logic.
AgentTask
, Project
, and LabelRowV2
.
If you type any parameter of your stage implementation (e.g., the my_agent
function) with one of these types, the system automatically injects the corresponding object, matching the task at hand.
For example:
project
variable automatically receives the workflow Project instance corresponding to the project_hash
defined or executed by the runner.
Similarly, access the task
and label_row
(associated with the given task) like this:
encord_agents.tasks.dependencies.Depends
type annotation using one of the following two patterns.
AgentTask
, Project
, LabelRowV2
, or other dependencies annotated with Depends
.
pre_execution_callback
parameter when defining your Runner.
python agent.py --project-hash=<your-project-hash>
. Before execution, we fetch the Project and run validation, which has access to the entire runner object. This validation occurs just before fetching and executing tasks, allowing you to perform arbitrary checks, including referencing agents, as shown above.
Runner
: This is a simple sequential runner to run the agent functions one after the other. It is easier to debug and understand. Use this for simple workflows or for testing out functionality before you scale it with the QueueRunner
.QueueRunner
: This is a more advanced runner that allows you to run the agent functions in parallel. It is useful when you have a lot of tasks to process and you want to speed up the processing time via parallel execution.Runner
and QueueRunner
QueueRunner
and the sequential Runner
are:
Feature | Runner | QueueRunner |
---|---|---|
Execution Model | Executes tasks sequentially in a single process | Designed for distributed execution across multiple processes |
Project Hash | Optional at initialization | Required at initialization |
Function Wrapping | Executes your function directly with injected dependencies | Additionally wraps your function to handle JSON task specifications |
Execution Control | Handles task polling and execution | You control task distribution and execution through your queue system |
Scaling | Not suitable for scaling | Suitable for scaling |