Triggers

Triggers start an agent Flow. Configure them from the Trigger node in the Flow builder, not from a separate agent-configuration page.

Current Flow canvas with the active Gmail trigger selected in the sidebar

Open the Trigger node

Open the agent’s Flow.
Select the Trigger node at the start of the Flow.
In the sidebar, select the trigger provider and then the configured trigger card.

The Trigger sidebar groups triggers by provider. Use Add trigger to set the Flow’s trigger; a Flow has one Trigger node rather than separate parallel triggers.

Configure a Gmail trigger

Selecting a Gmail New Email Received trigger opens its configuration in the Flow sidebar.

Current Gmail New Email Received trigger configuration in the Flow sidebar showing trigger name, Gmail connection, trigger context, filters, and Configure and test

Configure these fields for the trigger:

Field	Use it to
Trigger name	Give the trigger a recognizable name.
Connection	Choose the Gmail connection the trigger uses.
Trigger context	Add instructions that are sent with the trigger payload.
Filters	Narrow which messages start the Flow, including attachment, reply, and body-content filters.

Use Add condition and New Group to refine the filters. Select Configure & test when the setup is ready to test.

Configure a webhook trigger

Use a Webhook trigger when another system needs to start a Flow with an HTTP request.

Open the Flow’s Trigger node and add or select the Webhook trigger.
Copy the webhook URL shown in the trigger configuration. Do not construct the URL by hand.
Send a JSON POST request to that URL.

The webhook endpoint uses this form:

https://api.beamstudio.ai/agent-tasks/{agentId}/webhook/{triggerId}

The request body follows the current task-session payload. Include the target agentId and a taskQuery object with its required query string. You can also provide URLs or Base64-encoded context files when the Flow needs them.

{
  "agentId": "agent_123456",
  "taskQuery": {
    "query": "Process this customer inquiry"
  },
  "parsingUrls": ["https://example.com/customer-data"],
  "encodedContextFiles": [
    {
      "data": "BASE64_ENCODED_CONTENT",
      "mimeType": "application/pdf",
      "fileName": "inquiry.pdf",
      "fileSize": "2 MB"
    }
  ]
}

Use the exact URL and trigger-specific requirements shown in the Flow UI. Webhook authentication controls are not documented here because their current configuration surface has not been verified.

Test before publishing

Use Execute trigger to fetch trigger records and inspect their data before publishing the Flow. Use Execute flow when you want to test the complete Flow with a selected trigger record. After reviewing the trigger and Flow results, publish from the Flow header.

Next steps

Creating Flows

Add and configure the other nodes in an agent Flow.

Integrations

Connect the services used by Flow nodes and triggers.

Task Executions

Review runs that start from a trigger.

Publishing and deployment

Review publishing and Flow version history.

Getting Started

Building Agents

Running & Operations

Observability & Analytics

Resources

Open the Trigger node

Configure a Gmail trigger

Configure a webhook trigger

Test before publishing

Next steps

Creating Flows

Integrations

Task Executions

Publishing and deployment

​Open the Trigger node

​Configure a Gmail trigger

​Configure a webhook trigger

​Test before publishing

​Next steps

Creating Flows

Integrations

Task Executions

Publishing and deployment

Open the Trigger node

Configure a Gmail trigger

Configure a webhook trigger

Test before publishing

Next steps