Cloud storage tools

Cloud storage tools cover four agent jobs: read a customer's existing files, save the agent's outputs (reports, transcripts), generate shareable download links, and ingest a file into the agent's knowledge base for future RAG queries.

Shared action vocabulary

Every storage tool exposes the same actions where the underlying API supports them:

• list_objects — paginated listing with optional prefix.
• get_metadata — size, content-type, last modified.
• download — returns a presigned URL by default; inline: true returns base64 for files ≤ 5 MB with text-y MIME types.
• get_signed_url (S3 / Azure / GCS) or create_shared_link (Drive / Dropbox / OneDrive) — a short-lived URL the agent can drop in chat.
• upload — base64 payload or source_url to copy from.
• copy, delete.
• move, create_folder on Drive / Dropbox / OneDrive only.
• ingest_to_kb — pulls the file into the agent's knowledge base (chunks + embeds + persists). Available on every provider.

Hard caps that always apply

• 100 MB upload / download cap per call.
• 5 MB inline-base64 cap (text MIME types only).
• 7 days max signed-URL TTL.
• 500 items max per list page.

AWS S3 (and S3-compatible)

Tool id: aws_s3. Credential type: aws_s3.

Works with AWS, Cloudflare R2, MinIO, Backblaze B2, Wasabi — anything S3-compatible — by setting the optional endpoint field.

Setup (AWS)

1. In the IAM console, create a new user with programmatic access.
2. Attach a least-privilege policy — scope to the specific bucket and actions:

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

3. Save the Access Key ID + Secret Access Key + region + bucket as an AWS S3 credential.

Setup (Cloudflare R2)

1. In Cloudflare Dashboard → R2 → Manage R2 API Tokens, create a token scoped to one bucket.
2. Save the access key, secret, region (auto), bucket, and the R2 endpoint (https://{account_id}.r2.cloudflarestorage.com) as the credential.

Azure Blob Storage

Tool id: azure_blob_storage. Credential type: azure_blob_storage.

Setup

1. In the Azure portal, open your Storage Account → Access keys or Shared access signature.
2. Pick one auth path: full connection string, account key, or SAS token.
3. Save with the container name. Connection string is simplest; SAS is most scoped.

Google Cloud Storage

Tool id: google_cloud_storage. Credential type: google_cloud_storage.

Setup

1. In Google Cloud Console → IAM & Admin → Service Accounts, create one named chatzuri-agent.
2. Grant the minimum role — Storage Object Viewer for read, Storage Object Admin for writes/deletes. Scope to a single bucket, not the whole project.
3. Open the service account → Keys → Add key → JSON. Download the JSON file.
4. Paste the entire JSON into the serviceAccountKey field on a GCS credential, save with the bucket name.

Dropbox

Tool id: dropbox. Credential type: dropbox. Auth: OAuth.

Setup

1. Open dropbox.com/developers/apps and click Create app. API: Scoped access, permission type: App folder or Full Dropbox (your call).
2. Under Permissions, tick: files.content.read, files.content.write, files.metadata.read, sharing.write if you want shared links.
3. Save — Dropbox shows the App key and App secret.
4. Mint a refresh token via the Dropbox OAuth flow (one-time manual step today; see Dropbox OAuth Guide).
5. Save app key + app secret + refresh token as a Dropbox credential.

Google Drive

Tool id: google_drive. Credential type: google_drive. Auth: OAuth.

Same OAuth shape as Google Calendar — client id, client secret, refresh token. Scope: https://www.googleapis.com/auth/drive for full access or .../drive.file for per-file scoped.

Optional defaultFolderId — the folder used as parent when the agent uploads without specifying one.

OneDrive (Microsoft Graph)

Tool id: onedrive. Credential type: onedrive. Auth: OAuth.

Setup

1. In Azure portal → Microsoft Entra ID → App registrations, click New registration.
2. Pick a tenant (single-tenant or multi-tenant), set redirect URI.
3. Under API permissions, add Microsoft Graph delegated permissions: Files.ReadWrite (or Files.Read for read-only), offline_access (for refresh tokens), User.Read.
4. Under Certificates & secrets, generate a client secret. Save the value immediately — it's shown once.
5. Mint a refresh token via the OAuth flow. Save client id + secret + refresh token + tenant as a OneDrive credential.

Internal storage vs. customer storage

Chatzuri stores its own files (KB documents, message attachments, lead form uploads) in an internal S3 bucket configured via environment variables. That's separate from the customer storage tools above — when you wire up your AWS S3 as a tool, the agent never sees chatzuri's internal bucket.