Agents – ProteusAI Reference

You message agents. An agent is an entity that perceives its environment, takes actions autonomously to achieve a goal, and may improve over time. Most agents on ProteusAI are powered by AI, but you can also create agents controlled by humans.

See Agent.

Create Agent

POST /api/agents

curl -L -X POST \
-H "Authorization: Bearer user-3a4d80a9c3cca7ffd1bc341f..." \
https://messaging-api.useproteus.ai/api/agents \
-d '{
      "name": "Support Bot",
      "goal": "You are a helpful assistant. Always answer questions in a kind and helpful manner.",
      "orgId": "6816330b6f46b5afc080fbf7"
    }'

{
  "ok": true,
  "data": {
    "id": "681998f5474dbe26fe2e7f5f",
    "name": "Support Bot",
    "canSendWelcomeMessage": true,
    "createdAt": "2025-05-06T05:07:01.621Z",
    "description": null,
    "goal": "You are a helpful assistant. Always answer questions in a kind and helpful manner.",
    "isPublic": false,
    "isTemplate": false,
    "orgId": "6816330b6f46b5afc080fbf7",
    "tags": [],
    "updatedAt": "2025-05-06T05:07:01.621Z",
    "welcomeMessage": null
  }
}

Get Agent

GET /api/agents/:agentId

curl -L \
-H "Authorization: Bearer user-3a4d80a9c3cca7ffd1bc341f..." \
https://messaging-api.useproteus.ai/api/agents/681998f5474dbe26fe2e7f5f

You have to be a member of an organization to view a non-public agent in that organization. Public agents are visible to everyone.

Update Agent

PUT /api/agents/:agentId

curl -L -X PUT \
-H "Authorization: Bearer user-3a4d80a9c3cca7ffd1bc341f..." \
https://messaging-api.useproteus.ai/api/agents/681998f5474dbe26fe2e7f5f \
-d '{ "description": "Handles billing questions" }'

Delete Agent

DELETE /api/agents/:agentId

curl -L -X DELETE \
-H "Authorization: Bearer user-3a4d80a9c3cca7ffd1bc341f..." \
https://messaging-api.useproteus.ai/api/agents/681998f5474dbe26fe2e7f5f

Get Agent MCP Servers

GET /api/agents/:agentId/mcps

Returns the MCP servers exposed to an agent through its app integrations. The agent must be visible to the calling user.

curl -L \
-H "Authorization: Bearer user-3a4d80a9c3cca7ffd1bc341f..." \
https://messaging-api.useproteus.ai/api/agents/681998f5474dbe26fe2e7f5f/mcps

{
  "ok": true,
  "data": [
    { "label": "mcp_server_label", "url": "https://myserver.com/mcp" }
  ]
}

Agents also support event handlers (/api/agents/:agentId/event-handlers). These connect an agent to a plugin that generates its replies. See the Management API agents reference for the full lifecycle, including event handlers.

Authentication Chats