Skip to main content
Custom agents let you plug your own HTTPS endpoints into Encord and trigger them in the Label Editor, or as part of your Workflow.

Triggers

For more information on how to trigger Agents, see Trigger Agents.
Custom agents can be triggered in three ways: What are the different types of triggers? Where can agents be triggered?

Per-task Triggering

To create and use a custom agent with a per-task trigger:
1

Set up your custom Agent endpoint

To learn how to set up a custom agent endpoint, see our documentation here.See here for examples of custom agents.
2

Configure the Agent in the Agent catalog

  1. Navigate to Agents in the left-hand navigation. The Agents catalog tab opens by default.
  2. Search for Custom agent and click Add.
  3. Give the Agent a meaningful name and description.
  4. Add an Endpoint URL pointing to where you custom logic is hosted. This can be a model inference endpoint, a script running on a server, or any other accessible URL.
  5. List the decision strings your endpoint may return. Leave empty if your endpoint does not branch.
  6. Click Add agent to save the configuration and enable the agent for use in your Projects. It is now listed in your list of agents.
Configuring an agent does not run the agent. The agent only processes tasks once you add it to a Project or Workflow, or trigger it manually in the Label Editor.
3

Make the Agent available

Choose where the agent is used. Agents can be in a Workflow, in the Label Editor, or both.
  1. Add an Agent stage to the Workflow
  2. Ensure the Auto tab is selected.
  3. Select the custom agent you configured in the Agent catalog.
  4. Copy the signing secret shown with the webhook configuration. Encord generates this secret, and your endpoint uses it to verify that each request comes from Encord. Store it as ENCORD_WEBHOOK_SECRET where your endpoint runs.
If you change the webhook configuration later, check the secret again.
  1. To enable the agent, set the Status to Live.
The agent is now configured and ready to process tasks as they arrive in the stage.
  • If the Workflow is attached to a Project, only Agents with a compatible Ontology and label target are available for selection.
  • How tasks progress through the Workflow is determined by the agent’s decision pathways.
The Agent is automatically available to Annotators working in Projects that match the Ontology set up during configuration. They can then run the agent on demand from the Label Editor by right-clicking and selecting the agent.

Batch Triggering

Webhook SDK support for Batch-Triggered Agents is available here.
To create and use a custom agent with a batch trigger:
1

Set up your custom Agent endpoint

To learn how to set up a custom agent endpoint, see our documentation here.See here for examples of custom agents.
2

Make the Agent available

  1. Add an Agent stage to the Workflow
  2. Select the Advanced tab in the Agent stage panel.
  3. Add any decision pathways you want to use. Leave empty if your endpoint does not branch.
  4. Under Webhook, add the URL of your custom agent endpoint.
  5. Set a batch size and a maximum wait time. The batch size is the number of tasks that will be sent to the agent at once, and the maximum wait time is how long Encord will wait for a batch to fill before sending it to the agent.
  6. Copy the signing secret shown with the webhook configuration. Encord generates this secret, and your endpoint uses it to verify that each request comes from Encord. Store it as ENCORD_WEBHOOK_SECRET where your endpoint runs.
If you change the webhook configuration later, check the secret again.
  1. Save your Workflow.
The agent is now configured and ready to process tasks in batches as they arrive in the stage.The maximum wait is counted from when each task enters the queue, not on a repeating timer. Once a threshold is met, Encord notifies again at every five-minute check until your agent processes the queue. After that, the next notification depends on when new tasks arrive.For example, with a batch size of 10 and a maximum wait of 30 minutes, if 3 tasks arrive at 9:00:
3

Build the Receiver

When tasks are waiting in the Agent stage, Encord sends a notification to your webhook URL. The notification doesn’t contain the tasks. It tells your endpoint which Project and stage have work waiting, and your endpoint then fetches and processes the tasks itself.Before you start, you need:
  • The package: encord-agents v0.2.10 or later, plus FastAPI if you use the FastAPI receiver: python -m pip install "encord-agents>=0.2.10" "fastapi[standard]".
  • Encord credentials for the receiver: the SSH key your Task Agent already uses to fetch and update tasks, set as ENCORD_SSH_KEY_FILE or ENCORD_SSH_KEY.
  • A publicly reachable HTTPS endpoint: Encord must be able to send POST requests to it. Because anyone who finds the URL can call it, your receiver must verify the signature on every request.
Verification only needs the signing secret, not your Encord credentials, so your receiver can check signatures before it has access to any credentials. You can set the secret as ENCORD_WEBHOOK_SECRET or pass it explicitly.
A deployment that verifies several Agent stages with one ENCORD_WEBHOOK_SECRET can stop working for stages you add, change, or copy into a new Project. Those stages can get their own secret, so your receiver rejects their requests and Encord records them as failed deliveries. Give each stage its own route and secret, as in Use a different secret per route below.
Your receiver must:
  1. Verify every request. Encord signs each request with the signing secret. Reject any request that fails verification with a 401.
  2. Check the Project. A valid signature proves the request came from Encord, not that it concerns a Project your endpoint should act on. Ignore notifications for other Projects.
  3. Respond with 200 straight away. Encord waits 180 seconds for a response and retries if it times out. Any status other than 200 is recorded as a failed delivery. Process the tasks in the background, after responding.
  4. Expect repeat notifications. Encord notifies again at every five-minute check while tasks remain in the queue. If your receiver processed the stage before responding, Encord could notify again while the first run is still going. Make sure your processing is safe to run more than once.
Build a FastAPI receiver:
  1. Create the app with get_encord_app. It installs exception handlers that turn failed verification into the right response, so unverified requests never reach your route.
  2. Define the stage logic on a Runner. This is the same @runner.stage function you would write for a polling Task Agent. It returns the pathway to move each task along.
  3. Get the notification with dep_task_notification. This dependency reads the raw request body, verifies the signature against ENCORD_WEBHOOK_SECRET, and returns a TaskNotification.
  4. Check the Project, then hand off. Return early for any other Project, then queue run_stage as a background task.
Returning None responds with 200, which is what Encord expects.To run it locally, save it as fastapi_task_notifications.py and run:
If you create FastAPI() directly instead of using get_encord_app, call add_notification_handlers(app). Without it, a request that fails verification returns an unhandled 500 instead of a 401.
To use another framework or a serverless platform, see Receive notifications on any framework.
4

Deploy and Test

  1. Deploy the receiver to a publicly reachable HTTPS URL, for example https://agents.example.com/encord/task-ready. Set ENCORD_WEBHOOK_SECRET, ENCORD_PROJECT_HASH, and your SSH key in the deployment’s environment.
  2. Add the URL to the Agent stage and copy the signing secret into ENCORD_WEBHOOK_SECRET, as described in Step 2. If you change the webhook configuration later, check the secret again.
  3. Send tasks to the stage and watch the receiver’s logs. You should see a 200 for each notification, and the stage’s tasks moving along their pathways.
Test locally before adding the URL to Encord. Sign a sample notification the way Encord does and post it to your running app. Any string works as ENCORD_WEBHOOK_SECRET for this test, as long as the app and the script use the same one.
If you change one byte of body after signing, or sign with a different secret, the same request returns 401.

Receiver Reference

Options and details for the receiver you built in Step 3.
run_stage accepts a project_hash, so one deployment can process stages across several Projects. Keep an explicit list of the Projects you serve, and pass the Project on only after checking it:
Use dep_task_notification_with_args when one ENCORD_WEBHOOK_SECRET can’t cover every route, for example when one service receives notifications for two stages with different secrets. It returns a dependency that verifies against the secret you pass.You can also widen the timestamp tolerance from its default of 300 seconds. Only do this for a host whose clock can’t be kept more accurate than that.
The TaskNotification your route receives has the following fields:To act on the reason, compare it against the enum, and treat anything else as unknown. Use isinstance to detect unknown reasons, because the enum subclasses str:
Because notifications repeat and counts go out of date, make your stage logic safe to run more than once. run_stage works from the stage’s queue as it is when it runs, so an extra notification only triggers another check of the queue.
encord_agents.core.webhooks works with any framework or serverless platform:
  • verify_and_parse_notification(body, headers, *, secret=None, tolerance_seconds=300) verifies the request and returns a TaskNotification. Header lookup is case-insensitive, so a lowercased AWS Lambda headers dictionary works as is.
  • verify_signature(body, *, signature, timestamp, secret=None, tolerance_seconds=300) only checks the signature, for when you extract the headers yourself.
  • parse_notification(body) only reads the body. It trusts its input, so call it after verification.
Always pass the body exactly as received, as bytes. The signature covers the raw bytes, so a body that has been parsed and re-serialized won’t verify.Map each exception to the status Encord expects:
To verify a request without the package, compute an HMAC-SHA256 hex digest of <timestamp>.<body> using the signing secret, and compare it with the X-Encord-Signature header. The Unix timestamp is in the X-Encord-Timestamp header.
Encord only reads the status code, and records anything other than 200 as a failed delivery. With get_encord_app or add_notification_handlers, each outcome maps to a status automatically:You can add one URL to more than one Workflow stage, which is why other event types are acknowledged rather than rejected. Encord adds new fields and reason values without changing the notification version, and the parser accepts them. It only rejects a new version, which Encord reserves for breaking changes.

Webhook Payload

See our documentation for webhook payloads here.

Script Triggering

To create and use a custom agent with a script trigger:
1

Set up your custom Agent endpoint

To learn how to set up a custom agent endpoint, see our documentation here.See here for examples of custom agents.
2

Make the Agent available

  1. Add an Agent stage to the Workflow
  2. Select the Advanced tab in the Agent stage panel.
  3. Add any decision pathways you want to use. Leave empty if your endpoint does not branch.
  4. Save your Workflow.
The Agent is now configured and ready to process tasks when triggered by an external script or process. Scripts to trigger agents take the following form:
Basic Example

Decision Pathways

Decision pathways are allow you to route tasks to different downstream stages based on the outcome of the Agent. How decision pathways are set up depends on the trigger type of the Agent.

For Per-Task Trigger Agents

Custom Agents with a Per-Task trigger can route each task down one of several decision pathways. Each pathway represents a possible outcome of the Agent, such as accept, reject, or needs_review.To use decision pathways, define them when you configure the Agent in the Agent catalog. When you then add the Agent to a Workflow, Encord replaces the Agent stage’s default single pathway with one named pathway for each decision you defined. You can connect each pathway to a different downstream stage, so tasks move through the Workflow based on the Agent’s decision.

For Batch & Script Triggered Agents

Custom Agents with a Batch or Script trigger can route each task down one of several decision pathways. Each pathway represents a possible outcome of the Agent, such as accept, reject, or needs_review.To add decision pathways to a Batch or Script triggered Agent:
  1. Add an Agent stage to a Workflow.
  2. Navigate to the Advanced tag in the Agent stage panel.
  3. Add a decision pathway for each possible outcome of the Agent.