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.

​
Custom Agents in the Agents Catalog

Only HTTPS endpoints are supported for Custom Agents.
To register a Custom Agent using the Agents Catalog:
  1. Go to Agents in the left-hand navigation.
  2. In the Agents catalog tab, select the Custom agent tile.
  1. Fill in the form:
    • Give the agent a clear name and description.
    • Provide the public HTTPS endpoint that Encord should call.
    • Enter possible decisions that the agent can return (for example, “approve” or “reject”). These decisions are represented as pathways in the Workflow. If your agent does not return decisions, you can leave this field blank.
  2. Save the configuration to register the Custom Agent.

​
Setting Up Custom Agents

For end-to-end examples (including example payloads and code), visit our Agents documentation here.
Before you can register a Custom Agent, you must create and host the HTTPS endpoint that acts as your agent. At a high level, your backend should:
  • Accept a JSON payload from Encord describing the current project, data item, and frame.
  • Use the Encord SDK or API (and any external models you choose) to perform work.
  • Write results back to Encord (for example, updating labels or classifications).
  • Return a successful HTTP status code so the editor knows the request completed.
Once saved, the agent appears in the Enabled tab of the Agents section.

​
Testing Custom Agent Endpoints

You can test your custom agent endpoint directly from the Encord platform to verify it’s working correctly before using it in production.
After registering your Custom Agent, you can test its endpoint:
  1. Navigate to your agent in the Enabled tab.
  2. Click the Test tab in the agent details page.
  3. Configure the test payload with sample data (project hash, data hash, and frame number).
  4. Click Test agent to send a request to your endpoint.
The test sends requests directly from your browser to your endpoint. Your agent must allow CORS requests from the Encord domain (e.g., https://app.encord.com) for testing to work. If your agent restricts access by source IP, you must allow your current IP address for testing.
A successful test from your browser does not guarantee that Encord’s servers can reach your endpoint. Ensure your endpoint is accessible from Encord’s infrastructure for production use.

​
Using Custom Agents

The Agent is triggered:
  • In the Label Editor: On demand by the Tasker while annotating or reviewing a task. See here for more information.
  • From your Workflow: On tasks that pass through the Workflow node. Custom agents are triggered in the same way as other Agents. Click here to learn more.

​
Custom Workflow Agents - Manual

If your custom agent should be triggered manually, open the Advanced tab in the Agent node configuration to set them up. Tasks in this Agent stage do not proceed through the workflow unless the agent is triggered manually. When setting up an agent as “advanced”, you do not directly assign a custom agent. Instead, you are hosting a service that picks up tasks from the Workflow stage, performs an action, and then progresses the task to the next stage.

​
Examples

​
End-to-End Agent Examples

We provide end-to-end examples of custom agent implementation using Jupyter Notebooks here.