S3

File uploads to Amazon S3 buckets trigger agents to process documents, images, and data files with AI.

Setup Instructions

1. 1

   Create an S3 bucket

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

2. 2

   Create the connector

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

3. 3

   Configure, create, and copy the Webhook URL and Secret Key

   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 and Secret Key in the Configuration section. Copy both. To view them later, hover over the connector in the Connector Flow and click the Eye icon.

4. 4

   Set up S3 Event Notifications

   Configure the 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 the bucket. Configure S3 to send events through SNS HTTP subscription or Amazon EventBridge to the connector's webhook URL. Events are filtered by prefix/suffix and dispatched to linked agents.

The linked 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.

When "Include Content" is enabled, text and JSON files are decoded as UTF-8. Binary files are base64 encoded. Each object event creates a separate input with one file, capped at the configured 1–10 MiB limit. Oversized or unavailable content is omitted while bucket, key, and available file and event metadata remain; content.skipped and file_issues explain the omission.

File content is optional by default. Enable Files required on the agent link, or set files_required: true in its configuration, to fail before execution when content is missing or omitted. Input review can also omit optional content that exceeds its review budget. Agent-run IDs are stable for repeated delivery of the same object event to the same linked agent, so retries reuse the run.

Notifications accept up to 100 records in a 10 MiB body. Each serialized object input is capped at 15 MiB; Connic first omits file content if it exceeds that cap. Metadata alone exceeding the cap returns HTTP 400 with input_too_large rather than requesting a retry.

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

• 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 are silently ignored.

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

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

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

# 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:*"]
    }]
  }'

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

# 2. Create EventBridge rule with API Destination target using:
# <connector-url>?secret=<secret-key>
# (Configure via AWS Console or CloudFormation)