Agent Event Handlers – ProteusAI Reference

🚫

Internal use only!

An agent event handler is a plugin instance that listens for agent events. These event handlers may also receive tokens that allow them to send messages on behalf of the agents to which they are attached.

Add Agent Event Handler

POST /api/agents/:agentId/event-handlers

This endpoint adds a plugin instance as an event handler for an agent. The response of the API is the plugin instance.

curl https://management-api.useproteus.ai/api/agents/6819a0e484df0fc342cea506/event-handlers \
    -X POST \
    -H "Authorization: Bearer user-3a4d80a9c3cca7ffd1bc341f.ede04d00e4b168bed35d9fcde8c2f92f.00d7fecf89201691f94b01e5b294da65.e7ea4c191b2c9a059ce5658deb7349c26a931ed8b7a04bf0" \
    -d '{
            "name": "GPT-4o Message Processor",
            "pluginId": "681f23cc38780a323859233f",
            "events": ["AGENT_MESSAGE_RECEIVED"],
            "scopes": ["AGENT_MESSAGE_WRITE"],
            "eventDispatchMode": "SYNC",
            "inputs": {
                "apiKey": "sk-proj-your-api-key"
            }
        }'

This API call dispatches the PLUGIN_INSTALLED event to the webhook of the plugin as a HTTP POST request.

List Agent Event Handlers

GET /api/agents/:agentId/event-handlers

This endpoint lists the plugin instances acting as event handlers for an agent. The agent must be visible to the current user for this API call to succeed.

curl https://management-api.useproteus.ai/api/agents/6819a0e484df0fc342cea506/event-handlers \
    -H "Authorization: Bearer user-3a4d80a9c3cca7ffd1bc341f.ede04d00e4b168bed35d9fcde8c2f92f.00d7fecf89201691f94b01e5b294da65.e7ea4c191b2c9a059ce5658deb7349c26a931ed8b7a04bf0"

Delete Agent Event Handler

DELETE /api/agents/:agentId/event-handlers/:pluginInstanceId

This endpoint deletes a plugin instance acting as an event handler for an agent. The current user must be a member of the org with a role of OWNER.

curl https://management-api.useproteus.ai/api/agents/6819a0e484df0fc342cea506/event-handlers/6823341466b90fb047739892 \
    -X DELETE \
    -H "Authorization: Bearer user-3a4d80a9c3cca7ffd1bc341f.ede04d00e4b168bed35d9fcde8c2f92f.00d7fecf89201691f94b01e5b294da65.e7ea4c191b2c9a059ce5658deb7349c26a931ed8b7a04bf0"

This API call dispatches the PLUGIN_UNINSTALLED event to the webhook of the plugin as a HTTP POST request.

Async vs Sync Agent Event Handlers

Stopping Event Propagation

Plugins App Integration