Skip to main content
This section defines the interface for Custom Agents. Use it to define agents via the library or when writing your own implementation.

​
Schema

type AgentPayload = {
  projectHash: string;
  dataHash: string;
  frame: number;
  objectHashes?: string[];
};
This schema aligns with the FrameData structure. Notably, the objectHashes: string[] type represents that the field is either not present or present and a list of strings.

​
Test Payload

When you register your Custom Agent in the platform’s Custom Agents section, you can test it with a test payload. If you modify this payload, the platform verifies your agent’s access to the associated project and data. Otherwise, the platform sends a distinguished X-Encord-Agent Header, which automatically prompts an appropriate response. This allows you to test that you deploy your agent appropriately, that your session sees the Agent (all requests to your agent originate from your browser session, not the Encord backend), and that it works on particular projects.

​
Webhook Security

Encord provides webhook signing secrets to verify the authenticity of requests sent to your custom agent endpoints. Each custom agent endpoint receives a unique signing secret that you can use to validate incoming webhook payloads.

​
Accessing Your Signing Secret

You can view and copy your custom agent’s signing secret from the Encord platform:
  1. Navigate to your workflow configuration
  2. Select your custom agent node
  3. Locate the Signing secret section
  4. Use the eye icon to reveal the secret or the copy icon to copy it to your clipboard
The signing secret is automatically generated when you configure your custom agent endpoint URL. Save your workflow after changing the URL to update the secret.

​
Verifying Webhook Signatures

Use the signing secret to verify that webhook requests to your custom agent endpoint originate from Encord. This helps protect your endpoint from unauthorized requests and ensures data integrity. For detailed implementation guidance on webhook signature verification, see the webhook security documentation.

​
Response

The platform displays your agent’s output using the AgentResponse type, making your agents more interactive and informative. For example, when the label state does not conform to the Custom Agent’s expectation or if the agent’s function involves checking the validity of current labels, the response type offers a way to communicate this information to the annotator.

​
Error Handling

Raise an EncordAgentException for appropriate error handling. For instance, if your agent requires triggering on polygons but receives a skeleton, return an informative error to the Encord platform. Additionally, in the event of an authorization issue with the Encord platform (for example, a request attempts to access a Project the agent does not have access to), the response body includes the authorization message within an AgentErrorResponse type: 
type EditorAgentErrorResponse = {
  message?: string;
}
The platform displays this message to allow intuitive usage of your agent.