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.
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:
{
"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:
{
"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.
{
"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)
# 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
# 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.