S3 Agent

The s3 agent connects to Amazon S3 using AWS credentials. It downloads objects from buckets and uploads workspace files to S3 keys. Refs use standard S3 URI format (s3://bucket/key) or the shorthand bucket/key.

Unlike action-based agents, s3 infers direction from the phase configuration: use sources to download, use target_entries to upload. There is no action field.

---

Sample Phase

- name: fetch-config
  agent: s3
  sources:
      - name: config.json
        ref: "s3://my-bucket/configs/production.json"

---

Phase Configuration

Direction Inference

The s3 agent has no action field. Direction is determined by which field you provide:

Field	Direction	Behavior
sources	Download	Fetches objects from S3, writes to workspace
target_entries	Upload	Uploads workspace files to S3

Phase YAML Fields

Field	Type	Required	Description
name	string	Yes	Unique phase name within the workflow
type	string	No	Defaults to "standard"
agent	string	Yes	Must be "s3"
depends_on	string[]	No	Upstream phases that must complete before this phase runs
sources	SourceEntry[]	Required unless target_entries	Objects to download from S3
target_entries	TargetEntry[]	Required unless sources	Objects to upload to S3

Source Entry Fields

Field	Type	Required	Description
name	string	Yes	Output filename (written to .cliq/files/{phase}/{name})
ref	string	Yes	S3 URI: s3://bucket/key or bucket/key

Target Entry Fields

Field	Type	Required	Description
name	string	Yes	Identifier for the upload
ref	string	Yes	Destination S3 URI: s3://bucket/key
file	string	Yes	Local workspace file path to upload

Ref Formats

Pattern	Example	Behavior
s3://bucket/key	s3://my-bucket/config/app.json	Standard S3 URI
bucket/key	my-bucket/config/app.json	Shorthand (s3:// prefix optional)

---

Settings

AWS credentials are configured under agents.s3 in settings.json:

Key	Required	Default	Description
agents.s3.access_key_id	Yes	—	AWS access key ID
agents.s3.secret_access_key	Yes	—	AWS secret access key

The AWS_REGION environment variable is also respected (defaults to us-east-1).

---

Output

Handoff Structure

Source operations return object metadata; target operations confirm the upload with an ETag.

Download sources

{
    "data": {
        "sources": {
            "config": {
                "ref": "s3://my-bucket/config/app.json",
                "bucket": "my-bucket",
                "key": "config/app.json",
                "size_bytes": 2048
            }
        },
        "targets": {}
    },
    "text": "## S3 Results\n\n✓ Fetched config — my-bucket/config/app.json (2048 bytes)"
}

Upload targets

{
    "data": {
        "sources": {},
        "targets": {
            "report": {
                "ref": "s3://my-bucket/reports/latest.json",
                "bucket": "my-bucket",
                "key": "reports/latest.json",
                "etag": "\"d41d8cd98f00b204e9800998ecf8427e\""
            }
        }
    },
    "text": "## S3 Results\n\n✓ Uploaded report → my-bucket/reports/latest.json"
}

Field Reference

Field	Location	Description
ref	data.sources.*, data.targets.*	Original S3 URI from YAML
bucket	data.sources.*, data.targets.*	S3 bucket name
key	data.sources.*, data.targets.*	Object key within the bucket
size_bytes	data.sources.*	Downloaded object size in bytes
etag	data.targets.*	S3 ETag from the PutObject response (confirms successful upload)

Files Written

Source operations write to .cliq/files/{phase}/{source.name}:

• Objects are downloaded as-is (JSON, text, binary, etc.)
• Content type is preserved from the S3 object metadata

Downstream Access

Reference handoff data in downstream phases using template variables:

- name: process
  agent: cursor
  prompt: |
      Parse the config from bucket "$(handoff.fetch-config.sources.config.bucket)"
      at key "$(handoff.fetch-config.sources.config.key)".

---

Examples

Example: Fetch config and apply it

Download a configuration file from S3 and use it to drive implementation.

phases:
    - name: fetch-config
      agent: s3
      sources:
          - name: config
            ref: "s3://my-app-configs/production/settings.json"

    - name: apply
      agent: cursor
      depends_on: [fetch-config]
      prompt: |
          Read the production config ($(handoff.fetch-config.sources.config.size_bytes) bytes)
          and update the local environment to match.

Example: Download test fixtures

Pull test data from S3 to use in a test generation pipeline.

phases:
    - name: fetch-fixtures
      agent: s3
      sources:
          - name: users
            ref: "s3://test-data/fixtures/users.json"
          - name: orders
            ref: "s3://test-data/fixtures/orders.json"

    - name: generate-tests
      agent: cursor
      depends_on: [fetch-fixtures]
      prompt: |
          Using the test fixtures for users and orders,
          generate integration tests for the checkout flow.

Example: Upload build artifacts

Generate a report and upload it to S3 for archival.

phases:
    - name: build-report
      agent: cursor
      role: analyst
      prompt: |
          Analyze the codebase and generate a coverage report.
          Save it to coverage-report.json.

    - name: archive
      agent: s3
      depends_on: [build-report]
      target_entries:
          - name: report
            ref: "s3://build-artifacts/reports/coverage-latest.json"
            file: coverage-report.json

Example: Fetch data, process, and upload results

A complete round-trip: download raw data, process it, and upload the results.

phases:
    - name: fetch-raw
      agent: s3
      sources:
          - name: raw-data
            ref: "s3://data-lake/raw/events-2024-01.json"

    - name: transform
      agent: cursor
      depends_on: [fetch-raw]
      prompt: |
          Transform the raw event data into a summary report.
          Output the result to summary.json.

    - name: upload-results
      agent: s3
      depends_on: [transform]
      target_entries:
          - name: summary
            ref: "s3://data-lake/processed/events-summary-2024-01.json"
            file: summary.json

---

Setup

1. Create an IAM user (or use an existing one) with S3 access permissions
2. Generate an access key pair in the AWS Console under IAM → Users → Security credentials
3. Ensure the IAM policy grants at minimum s3:GetObject (for sources) and s3:PutObject (for targets) on the relevant buckets

echo $AWS_ACCESS_KEY_ID | cliq settings agents.s3.access_key_id --stdin --global
echo $AWS_SECRET_ACCESS_KEY | cliq settings agents.s3.secret_access_key --stdin --global
cliq doctor agent s3

Optionally set the AWS region if your buckets are not in us-east-1:

export AWS_REGION=eu-west-1

---

See Also

• Agent Overview
• Agent SDK