Triggers
For more information on how to trigger Agents, see Trigger Agents.
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

- Navigate to Agents in the left-hand navigation. The Agents catalog tab opens by default.
- Search for Custom agent and click Add.
- Give the Agent a meaningful name and description.
- 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.
- List the decision strings your endpoint may return. Leave empty if your endpoint does not branch.
- 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.

In a Workflow
In a Workflow

- Add an Agent stage to the Workflow
- Ensure the Auto tab is selected.
- Select the custom agent you configured in the Agent catalog.
- 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_SECRETwhere your endpoint runs.
- To enable the agent, set the Status to Live.
- 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.
In the Label Editor
In the Label Editor
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.
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

- Add an Agent stage to the Workflow
- Select the Advanced tab in the Agent stage panel.
- Add any decision pathways you want to use. Leave empty if your endpoint does not branch.
- Under Webhook, add the URL of your custom agent endpoint.
- 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.
- 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_SECRETwhere your endpoint runs.
- Save your Workflow.
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:Returning To use another framework or a serverless platform, see Receive notifications on any framework.
- The package:
encord-agentsv0.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_FILEorENCORD_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.
ENCORD_WEBHOOK_SECRET or pass it explicitly.Your receiver must:- Verify every request. Encord signs each request with the signing secret. Reject any request that fails verification with a 401.
- 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.
- 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.
- 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.
- 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. - Define the stage logic on a
Runner. This is the same@runner.stagefunction you would write for a polling Task Agent. It returns the pathway to move each task along. - Get the notification with
dep_task_notification. This dependency reads the raw request body, verifies the signature againstENCORD_WEBHOOK_SECRET, and returns aTaskNotification. - Check the Project, then hand off. Return early for any other Project, then queue
run_stageas a background task.
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.4
Deploy and Test
- Deploy the receiver to a publicly reachable HTTPS URL, for example
https://agents.example.com/encord/task-ready. SetENCORD_WEBHOOK_SECRET,ENCORD_PROJECT_HASH, and your SSH key in the deployment’s environment. - 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. - 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.
ENCORD_WEBHOOK_SECRET for this test, as long as the app and the script use the same one.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.Serve several Projects
Serve several Projects
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 a different secret per route
Use a different secret per route
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.Notification fields
Notification fields
The Because notifications repeat and counts go out of date, make your stage logic safe to run more than once.
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: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.Receive notifications on any framework
Receive notifications on any framework
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 aTaskNotification. 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.
<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.Responses and errors
Responses and errors
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

- Add an Agent stage to the Workflow
- Select the Advanced tab in the Agent stage panel.
- Add any decision pathways you want to use. Leave empty if your endpoint does not branch.
- Save your Workflow.
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.Per-Task Triggered Agents
Per-Task Triggered Agents
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 asaccept, 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.Batch & Script Triggered Agents
Batch & Script Triggered Agents
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 asaccept, reject, or needs_review.To add decision pathways to a Batch or Script triggered Agent:- Add an Agent stage to a Workflow.
- Navigate to the Advanced tag in the Agent stage panel.
- Add a decision pathway for each possible outcome of the Agent.

