@sisu-ai/tool-aws-s3

v2.0.6

Published

8 days ago

Work with AWS S3 from agents using safe tools for reading, listing, writing, and metadata access.

0High
0Medium
0Low

lejahmie

sisu ai ai-agent agentic tool aws-s3

@sisu-ai/tool-aws-s3

Work with AWS S3 from agents using safe tools for reading, listing, writing, and metadata access.

Exports

s3GetObject({ bucket, key }) → { content: string }
s3ListObjects({ bucket, prefix? }) → string[]
s3ListObjectsDetailed({ bucket, prefix? }) → { key: string; lastModified?: string; size?: number }[]
s3GetObjectMetadata({ bucket, key }) → Record<string, string> (user metadata)
s3PutObject({ bucket, key, content }) → { ok: true } | { ok: false, error: string }
s3DeleteObject({ bucket, key }) → { ok: true } | { ok: false, error: string }

Write operations are guarded. When disabled, write tools return { ok: false, error } (they do not throw).

Configuration

Region: AWS_REGION or AWS_DEFAULT_REGION (defaults to us-east-1)
Credentials (optional): AWS_ACCESS_KEY_ID + AWS_SECRET_ACCESS_KEY when set; otherwise it relies on the default credential chain
Optional client injection: Provide your own client via ctx.state.s3.client (v3 S3Client or v2‑like shape with getObject, listObjectsV2, putObject, deleteObject, headObject).
Write guard (default: disabled):
- ctx.state.s3.allowWrite = true, or
- AWS_S3_ALLOW_WRITE=1.

Usage

import { Agent } from '@sisu-ai/core';
import { registerTools } from '@sisu-ai/mw-register-tools';
import { s3GetObject, s3ListObjectsDetailed, s3DeleteObject } from '@sisu-ai/tool-aws-s3';

const app = new Agent().use(registerTools([
  s3GetObject, s3ListObjectsDetailed, s3DeleteObject
]));

// Optional: tweak write policy; region/creds read from env
ctx.state.s3 = { allowWrite: false };

Env vars commonly used

AWS_REGION or AWS_DEFAULT_REGION
AWS_ACCESS_KEY_ID and AWS_SECRET_ACCESS_KEY (optional if using instance/profile/role creds)
AWS_S3_ALLOW_WRITE (set to 1/true to enable writes)

Read “latest” example

const items: any[] = await s3ListObjectsDetailed.handler({ bucket: 'my-bucket', prefix: 'folder/' } as any, ctx) as any;
const latest = items
  .filter(i => i.lastModified)
  .sort((a,b) => (a.lastModified! < b.lastModified! ? 1 : -1))[0]?.key;
if (latest) {
  const { content } = await s3GetObject.handler({ bucket: 'my-bucket', key: latest } as any, ctx) as any;
  // optionally delete
  await s3DeleteObject.handler({ bucket: 'my-bucket', key: latest } as any, ctx);
}

Community & Support

Discover what you can do through examples or documentation. Check it out at https://github.com/finger-gun/sisu. Example projects live under examples/ in the repo.