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.

​
Set Up Custom Agents

First 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.

​
Installation

We recommend installing the Encord agents library in an isolated environment. To install encord-agents in your current environment, run:
Installing the vision extras is advised for most users. These dependencies optimize performance when handling visual data formats.
Encord Agents requires python >= 3.10. If you do not have Python 3.10, we recommend usingpyenv to manage your Python versions.

​
Register Custom Agents

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.

​
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 (for example: 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.