Usage

This guide walks through creating a trigger using Airtable that executes your agent when new records are added to your Airtable base. The same workflow applies to other providers (Slack, Gmail, GitHub, Schedule).

To try this yourself

You'll need VoltOps Console access, a VoltAgent example or your own agent, and an Airtable account with a base and Personal Access Token (we'll show you how to create one).

Step 1: Trigger Connection

To set up a trigger, you first need to select a provider and configure its credentials.

In VoltOps Triggers page, click Add Trigger, select Airtable provider, choose Record created event, and click New credential to configure authentication.

• Connection Name: Name for this credential ("Airtable credential")

• Authentication: Select Personal access token (OAuth 2.0 is also supported)

• Access Token: Go to Airtable Token Creation and create a new token with the following scopes:

data.records:read
data.records:write
schema.bases:read

After pasting the token, click Save credentials to proceed to trigger options.

Step 2: Trigger Configuration

After configuring credentials, you need to specify which Airtable base, table, and field to monitor for new records. These settings determine when and how the trigger fires.

Set the following trigger options based on your Airtable base structure:

• Base: Select your Airtable base → AI Model Experiment Tracker

• Table: Select the table to monitor for new records → Experiments

• View: (Optional) Select a specific view to monitor

• Trigger Field: Select the field that indicates when a record was created → createdTime

• Poll Interval: Set how often to check for new records (in seconds) → 60 (lower values increase API usage)

Click Next to review your settings, then create the binding with Draft status. Next, we'll need to add targets next to activate it.

Step 3: Add Target to Activate Binding

After creating your binding, you need to add targets that will execute when the trigger fires. Click Add Your First Target to open the target configuration wizard.

The target configuration is a 2-step process:

Step 3.1: Add Trigger Handler to Your Project

First, you need to add a trigger handler to your VoltAgent project. This is the code that will process incoming trigger events.

The wizard displays a code snippet that you need to copy and add to your VoltAgent project:

import { VoltAgent, createTriggers } from "@voltagent/core";

new VoltAgent({
  //
  triggers: createTriggers((on) => {
    on.airtable.recordCreated(({ payload }) => {
      console.log(payload);
    });
  }),
});

What this code does:

• Creates a new VoltAgent instance with trigger handlers
• Uses createTriggers to define trigger event handlers
• on.airtable.recordCreated registers a handler for the Airtable record created event
• Receives the trigger payload (Airtable record data) when the event fires

Default endpoint path: Based on your trigger configuration, the system generates an endpoint path like:

POST /triggers/airtable/recordCreated

VoltAgent creates this route when you add the trigger handler to your agent. The trigger sends HTTP requests to this endpoint when events occur.

Important

After adding the snippet to your project:

1. Ensure your VoltAgent server is running
2. Check the "I've added the snippet to my project" checkbox
3. Click Continue to proceed to delivery configuration

Step 3.2: Configure Delivery Target

After adding the trigger handler code, configure how the trigger will deliver events to your endpoint.

General

• Target Name: A descriptive name for this target → Example: Airtable trigger handler

Delivery

• Destination

  Choose where VoltOps should send trigger events. You have three options:

  • Agent Servers

    Registered servers appear here with their name and URL. Select a server to send trigger events to it.

    To register a new server, click Create Agent Server and provide:

    • Name: A name for your server (e.g., Production server)
    • URL: The root URL of your VoltAgent server (e.g., https://your-deployed-voltagent-server.com)
    • Tags (optional): Organize your servers with tags
    tip

    For local development, see the Volt Tunnels section below to expose your local server.

  • Volt Tunnels

    Volt Tunnels expose your local development server to the internet via a secure HTTPS connection. Use this to test triggers against your local VoltAgent instance without deploying to a remote server.

    This section shows your active local tunnels. If you don't have an active tunnel yet, click Start Local Tunnel to open a setup modal.

    The modal displays the command you need to run in your terminal. Once you run the command, the modal enters a waiting state with a loading indicator.

    pnpm volt tunnel 3141

    This gives you a secure HTTPS URL such as https://happy-cat-42.tunnel.voltagent.dev. Use it as the delivery target.

    note

    When your tunnel becomes active, it appears in the destination dropdown. Core+ users receive permanent tunnel URLs with custom usernames, while free tier users get random temporary URLs.

  • Custom HTTPS URL

    Select Custom HTTPS URL to send trigger events to your own webhook endpoint.

    HTTPS URL: Enter the URL where you want to receive trigger events (e.g., https://your-webhook.endpoint). VoltOps forwards the trigger payload to this address with retries and error tracking enabled.

    HTTP method: Choose the HTTP method for the request. Select POST (default), PUT, or PATCH depending on your webhook endpoint requirements.

    After selecting a destination, configure the endpoint path where your trigger handler is registered.

Endpoint Path

Specify the path where VoltAgent listens for this trigger:

• Default: /triggers/airtable/recordCreated (generated based on provider and event)
• You can change this if your handler uses a different path

tip

VoltAgent listens on this route when you add the trigger handler to your agent configuration. Keep it unless you've customized your server routing.

Test Connection

After configuring your delivery destination and endpoint path, click Test Connection to verify your endpoint is accessible.

Possible results:

• Endpoint is responding correctly: Your endpoint is ready to receive triggers
• 404 Not Found: The endpoint doesn't exist. Verify you've added the trigger handler to your VoltAgent project
• Connection failed: The request failed with an error message. Ensure your VoltAgent server is running and accessible

Delivery Preview

Below the test connection area, you'll see a preview of the final delivery configuration showing the complete URL and HTTP method that VoltOps will use to send trigger events:

POST {destination-url}{endpoint-path}

For example: POST http://localhost:3141/triggers/airtable/recordCreated

Verify this matches your expected endpoint before saving.

Advanced (Optional)

Click Advanced to add custom HTTP headers to trigger requests:

• Header Name: Custom header key (e.g., X-API-Key)
• Header Value: Custom header value (e.g., your-secret-key)

Use this to add authentication headers or other custom metadata to trigger requests.

After configuring all settings, click Create target to save the delivery target. Your binding is now ready to activate!

Step 4: Activate Binding and Test

Now that your binding and target are configured, you can activate the trigger and test it with real data from Airtable. We'll verify the trigger execution by checking the agent's activity in VoltOps Console.

Test the trigger by adding a new record in your Airtable base:

1. Open your Airtable base and add a new record to the monitored table
2. Fill in the trigger field (e.g., Label field) and wait for the poll interval to pass

Go back to VoltOps Console and navigate to the Agents section from the sidebar. Click on the agent you connected to the trigger to view executions that were processed by the trigger.

You'll see a chart showing trigger execution history. We can use the Triggers and Add Trigger buttons to manage and add new triggers to this agent.