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

​
Schema

type EditorAgentPayload = {
  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 editor agent in the platform’s Editor 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-Editor-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.

​
Response

The platform displays your agent’s output via the EditorAgentResponse type, making your agents more interactive and informative. For example, when the label state does not conform to the editor 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 EncordEditorAgentException 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 EditorAgentErrorResponse type:

type EditorAgentErrorResponse = {
  message?: string;
}

The platform displays this message to allow intuitive usage of your agent.