beam-ai-team/create-beam-task-auto-trigger

Create Beam Task Auto-Trigger

Convert a Beam.ai task into an auto-trigger webhook script for scheduled execution.

Purpose

This skill automates the process of:

1. Fetching task details from a Beam.ai task URL
2. Extracting the original task payload
3. Detecting payload type (query-based vs email-triggered)
4. Creating a bash webhook script with the correct payload structure
5. Saving it to the webhook-scheduler for automated rotation

Time saved: ~15 minutes of manual work per webhook script

Safety Contract

Before creating or saving an auto-trigger webhook script, show the source task URL/ID, target agent/workspace, payload type, destination file path, schedule or rotation assumptions, and expected side effects. Require explicit user approval in the current turn before writing the webhook script or enabling any scheduled execution. Read-only task inspection and local draft generation do not require approval.

Supported Agent Types

The skill intelligently detects and handles three types of agent triggers:

1. Simple Query-Based Agents

Agents triggered by simple text queries with no additional data. The webhook sends:

{
  "query": "summarize the document",
  "timestamp": "2026-01-02T13:00:13Z"
}

2. Query-Based Agents with Attachments/Data

Agents triggered by queries that require attachments or additional context. The webhook sends:

{
  "query": "analyze the attached resume",
  "additionalInfo": "",
  "beamAgentOSTaskID": "7c516cc3-f8fa-4ffc-af65-5eee0aa2792a",
  "beamTaskId": "CAN-3",
  "beamTaskTimestamp": "2025-12-05T07:55:48Z",
  "attachments": [
    {
      "name": "Marcus_Chen_Resume.pdf",
      "type": "file",
      "key": "53919651-bb7a-44de-9d94-6cf540ff640f_7bba5443-4ef2-432b-b256-7a00ba6da373_Marcus_Chen_Resume.pdf"
    }
  ],
  "timestamp": "2026-01-02T13:00:13Z"
}

3. Email-Triggered Agents (Gmail/Workable Integration)

Agents triggered by email messages. The webhook sends the full email payload:

{
  "id": "196a54bba916edc4",
  "messageId": "196a54bba916edc4",
  "threadId": "196a54bba916edc4",
  "labelIds": ["UNREAD", "CATEGORY_PERSONAL", "INBOX"],
  "snippet": "email preview text",
  "headers": {
    "from": "[email protected]",
    "to": "[email protected]",
    "subject": "Email Subject"
  },
  "attachments": [...],
  "textPlain": "email body text",
  "textHtml": "<div>email body html</div>",
  "timestamp": "2026-01-02T13:00:13Z"
}

The skill automatically detects which type based on the task payload structure.

When to Use

• Convert an existing Beam task into a recurring webhook
• Create auto-trigger scripts for agent tasks
• Add tasks to the webhook scheduler rotation
• Reproduce task execution with the same payload

Prerequisites

.env file at project root with:

BEAM_API_KEY=<beam-api-key>
BEAM_WORKSPACE_ID=your_workspace_id

Dependencies: requests, python-dotenv (already installed)

Quick Start

# Interactive mode (recommended)
python 03-skills/create-beam-task-auto-trigger/scripts/create_auto_trigger.py

# With task URL
python 03-skills/create-beam-task-auto-trigger/scripts/create_auto_trigger.py \
  --task-url "https://app.beam.ai/{workspace}/{agent}/tasks/{task-id}"

# With all parameters
python 03-skills/create-beam-task-auto-trigger/scripts/create_auto_trigger.py \
  --task-url "https://app.beam.ai/..." \
  --webhook-url "https://api.beamstudio.ai/agent-tasks/{agent}/webhook/{webhook-id}" \
  --script-name "my-agent-task.sh"

# With file attachment (base64 encoded)
python 03-skills/create-beam-task-auto-trigger/scripts/create_auto_trigger.py \
  --task-url "https://app.beam.ai/..." \
  --webhook-url "https://api.beamstudio.ai/..." \
  --script-name "resume-screening.sh" \
  --attachment-file "/path/to/resume.pdf"

Workflow

Step 1: Provide Task URL

The task URL from Beam.ai (from the browser address bar):

https://app.beam.ai/505d2090-2b5d-4e45-b0f4-cc3a0b299aa8/8cb86b50-aa8f-4876-a3cb-7eb62e910528/tasks/1c08f856-d1a2-47c4-a62a-01ff7d24b3df

Step 2: Provide Webhook URL

The agent webhook URL (get from Beam agent settings):

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

Step 3: Script Name

Choose a descriptive name for the webhook script:

interview-scheduling-agent.sh
data-processing-task.sh

Step 4: Script Generation

The skill will:

• Fetch the task details using the Beam API
• Extract the original task payload
• Create a bash script with:
  • Correct webhook URL
  • Original task payload
  • Dynamic timestamp
• Save to 04-workspace/scripts/webhook-scheduler/webhooks/

Output

Created Script:

04-workspace/scripts/webhook-scheduler/webhooks/{script-name}.sh

Script Content:

#!/bin/bash
TIMESTAMP=$(date -u +%Y-%m-%dT%H:%M:%SZ)
TASK_PAYLOAD='{"id":"...","messageId":"...","timestamp":"__TIMESTAMP_PLACEHOLDER__",...}'
TASK_WITH_TIMESTAMP=$(echo "$TASK_PAYLOAD" | sed "s/__TIMESTAMP_PLACEHOLDER__/$TIMESTAMP/g")

curl --location 'https://api.beamstudio.ai/agent-tasks/{agent}/webhook/{webhook-id}' \
--form 'task="'"$TASK_WITH_TIMESTAMP"'"' \
--form 'encodedContextFiles="[{\"mimeType\":\"application/pdf\",\"fileType\":\"document\",\"fileExtension\":\"pdf\",\"data\":\"<base64-encoded-content>\"}]"'

Examples

Example 1: Interactive Mode

python 03-skills/create-beam-task-auto-trigger/scripts/create_auto_trigger.py

# Prompts:
# Task URL: https://app.beam.ai/.../tasks/abc123
# Webhook URL: https://api.beamstudio.ai/agent-tasks/.../webhook/xyz789
# Script name: my-task.sh

# Output:
# ✅ Created: 04-workspace/scripts/webhook-scheduler/webhooks/my-task.sh

Example 2: Command Line

python 03-skills/create-beam-task-auto-trigger/scripts/create_auto_trigger.py \
  --task-url "https://app.beam.ai/505d.../tasks/1c08f856..." \
  --webhook-url "https://api.beamstudio.ai/agent-tasks/8cb86.../webhook/17f4e..." \
  --script-name "interview-scheduling.sh"

Example 3: With File Attachment

python 03-skills/create-beam-task-auto-trigger/scripts/create_auto_trigger.py \
  --task-url "https://app.beam.ai/505d.../tasks/7c516cc3..." \
  --webhook-url "https://api.beamstudio.ai/agent-tasks/53919651.../webhook/36bf660f..." \
  --script-name "resume-screening.sh" \
  --attachment-file "/Users/yourname/Documents/Marcus_Chen_Resume.pdf"

# Output:
# ✅ Created: 04-workspace/scripts/webhook-scheduler/webhooks/resume-screening.sh
# 📎 Attachment: Marcus_Chen_Resume.pdf (base64 encoded)

Example 4: Test the Created Script

# Test the webhook immediately
bash 04-workspace/scripts/webhook-scheduler/webhooks/interview-scheduling.sh

Parameters

| Parameter | Required | Description | |-----------|----------|-------------| | --task-url | Yes* | Beam.ai task URL from browser | | --webhook-url | Yes* | Agent webhook URL from Beam settings | | --script-name | Yes* | Name for the webhook script (must end in .sh) | | --attachment-file | No | Path to file to attach (e.g., resume.pdf). Will be base64 encoded and included in payload | | --output-dir | No | Output directory (default: webhook-scheduler/webhooks) | | --workspace | No | Beam workspace: bid or prod (default: bid) |

* Required in CLI mode, prompted in interactive mode

How It Works

1. Parse Task URL - Extract workspace, agent, and task IDs
2. Fetch Task Details - Use Beam API with authentication
3. Extract Payload - Get taskQuery or originalTaskQuery from task
4. Encode Attachments (if --attachment-file provided) - Read file and encode to base64
5. Separate Payload Components - Split task payload and encoded context files
6. Generate Script - Create bash script using --form format with:
   • task field: Task payload with dynamic timestamp
   • encodedContextFiles field: Array of base64-encoded files
   • Proper JSON escaping for bash (\" instead of ")
   • Compact JSON format (no spaces after colons)
7. Save Script - Write to webhook-scheduler folder
8. Set Permissions - Make script executable

Format Details:

• Uses --form multipart format instead of --data JSON
• JSON is escaped for bash: {\"key\":\"value\"} becomes {\\\"key\\\":\\\"value\\\"}
• Compact JSON with separators=(',', ':') - no spaces
• Two separate form fields: task and encodedContextFiles

Integration with Webhook Scheduler

The created script is automatically added to the webhook rotation:

• Runs every 47 minutes (Monday-Saturday)
• Rotates through all scripts alphabetically
• Each script runs ~20-21 times per week (with 9 total scripts)

Error Handling

Common Issues:

| Error | Cause | Solution | |-------|-------|----------| | Invalid task URL | URL format incorrect | Use full URL from Beam browser | | Task not found | Task ID doesn't exist | Verify task ID in Beam dashboard | | Authentication failed | API key invalid | Check .env file credentials | | Webhook URL invalid | Missing agent/webhook ID | Get URL from Beam agent settings |

Tips

Finding Webhook URL:

1. Go to Beam agent settings
2. Navigate to "Webhooks" section
3. Copy the webhook URL

Script Naming:

• Use descriptive names: customer-onboarding.sh
• Use hyphens, not spaces: invoice-processing.sh
• Must end with .sh: my-task.sh

Testing:

• Always test the script after creation
• Check Beam dashboard for task creation
• Verify payload is correct

Notes

• Created scripts are executable by default
• Scripts use dynamic timestamps (current time when run)
• Payload structure is preserved from original task
• Automatically detects and handles both query-based and email-triggered agents
• For email-triggered agents, preserves full Gmail message payload including headers, attachments, and content
• Scripts can be edited manually after creation
• Compatible with GitHub Actions webhook scheduler

---

Version: 1.4 Created: 2026-01-02 Updated: 2026-01-05 Status: Production Ready

Changelog

v1.4 (2026-01-05)

• BREAKING CHANGE: Switched to --form multipart format (matches Beam API requirements)
• NEW: Separates task and encodedContextFiles into two form fields
• IMPROVED: Proper JSON escaping for bash (\" instead of ")
• IMPROVED: Compact JSON format with separators=(',', ':') (no spaces)
• IMPROVED: Only includes encodedContextFiles field when attachments exist
• FIXED: Scripts now match ground truth format from working webhooks
• All generated scripts use the correct format that Beam API expects

v1.3 (2026-01-05)

• NEW: Added --attachment-file parameter to attach files (PDFs, etc.)
• Files are automatically base64-encoded and included in webhook payload
• Supports custom file attachments that override task-extracted files
• Enhanced attachment format with proper mimeType and content fields

v1.2 (2026-01-05)

• Added support for query-based agents with attachments/data
• Enhanced detection logic to handle three agent types
• Preserves attachment metadata and task IDs for agents that need them
• Fixed candidate-screening-agent to include resume attachments

v1.1 (2026-01-02)

• Added support for email-triggered agents (Gmail/Workable integration)
• Automatic detection of payload type (query-based vs email-triggered)
• Full email payload preservation for Gmail-triggered agents
• Enhanced documentation with payload type examples

v1.0 (2026-01-02)

• Initial release
• Support for simple query-based agents
• Beam API authentication
• Webhook script generation