Connectors

AWS S3

Trigger agents when files are uploaded to Amazon S3 buckets. Process documents, images, and data files with AI.

Inbound (File Events)

Receive S3 event notifications when files are uploaded or modified. The agent receives file metadata and optionally the file content for processing.

Setup Instructions

Create an S3 bucket

In the AWS Console, create a bucket (or use an existing one) and note the bucket name and region.

Create the connector

Open your agent, click Add inbound connector in the Connector Flow, then Create New Connector and select S3.

Configure, create, and copy the Webhook URL

Enter Bucket, Region, AWS credentials, and optionally Prefix/Suffix filters and Include Content settings. Click Create and the detail drawer opens automatically with the Webhook URL in the Configuration section. Copy it. To view it later, hover over the connector in the Connector Flow and click the Eye icon.

Set up S3 Event Notifications

Configure your bucket to POST events to the Webhook URL via SNS HTTP subscription or Amazon EventBridge (see details below).

How Inbound Works

S3 connectors receive event notifications via webhook when objects are created in your bucket. Configure S3 to send events through SNS HTTP subscription or Amazon EventBridge to your connector's webhook URL. Events are filtered by prefix/suffix, then dispatched to linked agents.

Configuration

Bucket Name: The S3 bucket to monitor for file events
Region: AWS region where the bucket is located
Key Prefix: (Optional) Only trigger for keys starting with this prefix (e.g., uploads/)
Key Suffix: (Optional) Only trigger for keys ending with this suffix (e.g., .pdf)
Include Content: Download and include file content in payload (for text/JSON files)
Max File Size: Maximum file size to download when including content (1-100 MB)

IAM Permissions

Required only when "Include Content" is enabled:

iam-policy.json

{
  "Version": "2012-10-17",
  "Statement": [
    {
      "Effect": "Allow",
      "Action": [
        "s3:GetObject",
        "s3:HeadObject"
      ],
      "Resource": "arn:aws:s3:::my-bucket/*"
    }
  ]
}

Event Payload

Your agent receives file metadata enriched with S3 event information:

event-payload.json

{
  "bucket": "my-bucket",
  "key": "uploads/invoice-2024-001.pdf",
  "size": 245789,
  "etag": "d41d8cd98f00b204e9800998ecf8427e",
  "event_name": "ObjectCreated:Put",
  "event_time": "2024-01-15T10:30:00.000Z",
  "_s3": {
    "event_source": "aws:s3",
    "aws_region": "us-east-1",
    "request_id": "C3D13FE58DE4C810",
    "source_ip": "192.0.2.1"
  }
}

The _s3 metadata includes event source, region, request ID, and source IP.

File Content Download

When "Include Content" is enabled, text and JSON files are decoded as UTF-8. Binary files are base64 encoded. Files exceeding the max size are skipped.

payload-with-content.json

{
  "bucket": "my-bucket",
  "key": "uploads/data.json",
  "size": 1234,
  "etag": "a1b2c3d4e5f6...",
  "event_name": "ObjectCreated:Put",
  "event_time": "2024-01-15T10:30:00.000Z",
  "content": {
    "text": "{\"customer_id\": \"12345\", \"amount\": 234.56}",
    "content_type": "application/json",
    "size_bytes": 1234,
    "encoding": "utf-8"
  },
  "_s3": { ... }
}

For large files or binary content, your agent can download directly from S3 using the bucket/key from the payload.

Event Filtering

Object Created (Default): Triggers on Put, Post, Copy, CompleteMultipartUpload
All Events: Also triggers on deletes and restores

Use prefix/suffix filters to avoid processing unwanted files. Events that don't match filters are silently ignored.

S3 Event Notification Setup

Configure S3 to send events to your connector. Two options are supported:

Option 1: SNS HTTP Subscription (Recommended)

terminal

# 1. Create SNS Topic
aws sns create-topic --name s3-events

# 2. Add HTTP Subscription (your connector webhook URL)
aws sns subscribe \
  --topic-arn arn:aws:sns:us-east-1:123456789:s3-events \
  --protocol https \
  --notification-endpoint <connector-url>

# 3. Configure S3 bucket notifications
aws s3api put-bucket-notification-configuration \
  --bucket my-bucket \
  --notification-configuration '{
    "TopicConfigurations": [{
      "TopicArn": "arn:aws:sns:us-east-1:123456789:s3-events",
      "Events": ["s3:ObjectCreated:*"]
    }]
  }'

The connector automatically handles SNS subscription confirmation and unwraps notification envelopes.

Option 2: Amazon EventBridge

terminal

# 1. Enable EventBridge on your S3 bucket
aws s3api put-bucket-notification-configuration \
  --bucket my-bucket \
  --notification-configuration '{
    "EventBridgeConfiguration": {}
  }'

# 2. Create EventBridge rule with API Destination target
# (Configure via AWS Console or CloudFormation)

EventBridge provides more filtering options and integrates with other AWS services.

Connectors Overview

Learn about connector modes

AWS SQS

Queue-based agent triggers

HTTP Webhooks

Trigger agents via HTTP requests

Agent Configuration

Configure agents to process files