Skip to main content
Agents are the core actors in Monsteria. They represent the connection to an email mailbox and the intelligence powered by LLM providers.

​
Key Capabilities

  • Receive, read, craft, and send emails
  • Parse, process, and extract data from attachments and email content
  • Drive conversation towards configured actionable Events or as instructed
  • Classify intention of incoming emails and trigger events that occur and send webhooks to external systems
You can query, update, and manage Agents via the API or the Dashboard.

​
Attributes

Each Agent is configured with the following attributes:
  • id: string
  • llmProvider: OPENAI | ANTHROPIC - The LLM provider powering the Agent
  • model: string - The LLM model the Agent is powered by
  • instruction: string - The instructions guiding the Agent’s behavior
  • channelProvider: GMAIL | OUTLOOK - The email service provider
  • isConnectedToChannel: boolean - Whether the Agent is currently connected to its channel provider
  • isActive: boolean - Whether the Agent is currently active and able to process emails
  • address: string - The email address representing the Agent
  • name: string - The display name of the Agent
  • createdBy: string - The user ID who created the Agent
  • orgId: string - The organization ID the Agent belongs to
  • webhookUrl: string - (optional) The URL to which webhooks will be sent to
  • webhookSecret: string - (optional) A secret key for your system to validate incoming webhooks
  • eventConfigs: EventConfig[] - List of Event Configurations associated with the Agent. See the Event System page for details.
  • createdAt: Date - Timestamp when the Agent was created
  • updatedAt: Date - Timestamp when the Agent was last updated

​
Example

{
  "id": "363d715f-2714-4b30-943a-2dae0111440e",
  "llmProvider": "OPENAI",
  "model": "gpt-4.1",
  "instruction": "You are a receptionist at a dental clinic. Your task is to assist patients in scheduling, rescheduling, or canceling appointments.",
  "channelProvider": "GMAIL",
  "isActive": true,
  "address": "[email protected]",
  "name": "Janet Mendoza",
  "createdBy": "1f30b4c4-9f2c-4572-8bde-be9923ef8b41",
  "orgId": "b818f389-c1bb-4e24-8e69-8d22f738f379",
  "webhookUrl": "https://api.company.com/monsteria-webhook-handler",
  "webhookSecret": "blakebortles123!",
  "autoReplyEnabled": false,
  "isConnectedToChannel": true,
  "eventConfigs": [
    {
      "id": "332fd8d5-faab-4e70-8289-767abef001c7",
      "agentId": "93abd68b-c936-40c8-abe6-ec07eac24d1e",
      "displayName": "Appointment Request",
      "key": "appointment_request",
      "schema": {
        "name": "appointment_request",
        "schema": {
          "type": "object",
          "required": ["firstName", "lastName", "phoneNumber", "preferredDateTime"],
          "properties": {
            "lastName": {
              "type": "string",
              "description": "The last name of the individual making the appointment request."
            },
            "firstName": {
              "type": "string",
              "description": "The first name of the individual making the appointment request."
            },
            "phoneNumber": {
              "type": "string",
              "description": "The phone number of the individual making the appointment request."
            },
            "preferredDateTime": {
              "type": "string",
              "description": "The preferred time and date in ISO 8601 format for the appointment."
            }
          },
          "additionalProperties": false
        },
        "strict": true
      },
      "description": "Trigger when a customer requests an appointment",
      "waitForResponse": true,
      "stopConversation": false,
      "isActive": true,
      "createdAt": "2025-10-07 01:22:27.452+00",
      "updatedAt": "2025-10-07 01:22:47.143197+00"
    }
  ],
  "createdAt": "2025-10-07T12:34:56.789Z",
  "updatedAt": "2025-10-07T12:34:56.789Z"
}
See the Create an Agent page for details on creating and managing Agents.