> ## Documentation Index
> Fetch the complete documentation index at: https://docs.encord.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Custom Agents Specification

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

***

### Schema

```typescript theme={"dark"}
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

<Note>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.</Note>

#### 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](/platform-documentation/Annotate/annotate-webhooks-notifications#verifying-webhook-signatures).

***

### 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:

```typescript theme={"dark"}
type EditorAgentErrorResponse = {
  message?: string;
}
```

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