Google Cloud Storage
A RocketRide tool node that gives an agent read access to a Google Cloud Storage bucket. Pick it when an agent needs to discover object names in a bucket and pull one down to the engine host for further processing.
About Google Cloud Storage
Google Cloud Storage is Google Cloud's object storage service. Data is kept as objects inside buckets, addressed by a key that usually reads like a directory path, and access is governed by Google Cloud IAM. It is commonly used for data lakes, backups, media, and as the staging area between systems in a cloud pipeline.
What it does
The node has no data lanes and no control-plane connections; it exists purely as an agent tool. It exposes two read-only operations against one configured bucket: listing object names and downloading a single object to a temporary file on the engine host. Pick it over a generic HTTP client when the agent should stay scoped to one bucket — and optionally one prefix within it — with credentials and a download size cap held by the node rather than by the agent. It reads objects only; it cannot upload, delete, or otherwise modify a bucket.
As a tool
The server-name prefix is gcs, producing these registered functions.
| Function | Description |
|---|---|
gcs.list_files | List object names in the configured bucket. |
gcs.download_file | Download one object to a temporary file on the engine host and return its local path. |
list_files takes no required arguments. Optional prefix narrows the listing
and is appended to the node's configured Path Prefix; optional
max_results caps the number of names returned and defaults to 10. It returns
a list of object names. On failure it returns a single-element list whose entry
is an error string rather than raising.
download_file requires file_name, the object's name or path inside the
bucket, which is likewise resolved beneath the configured Path Prefix. On
success it returns success, local_path (the temporary file on the engine
host), and size in bytes. Every failure — client not connected, bucket not
configured, object over the size cap, or any GCS error — comes back as a
dictionary with a single error key, so an agent should check for error
before reading local_path.
Only the most recent download is retained: starting a new download deletes the previous temporary file, and anything left is removed when the node shuts down. An agent that needs a downloaded file must consume it before requesting the next one.
Configuration
Set the bucket the node is allowed to touch and how it authenticates; the rest has working defaults. Bucket Name is what makes the tool functions usable — without it both functions return a "Bucket name not configured" error. The node verifies its credentials and fetches the bucket at startup, so a bad key, a missing bucket, or insufficient permission fails the pipeline immediately rather than at the agent's first call.
Bucket Name
The name of the single Google Cloud Storage bucket this node reads. It is not
an argument the agent can supply, so one node instance means one bucket;
connect a second tool_gcs node to expose a second bucket to the same agent.
Path Prefix
An optional path inside the bucket that scopes every operation. When set, the
node normalizes it to end with / before use, so reports matches objects
under reports/ and not a sibling key such as reports-archive/2024.csv.
Object names the agent passes are resolved beneath it: with a prefix of
reports, download_file called with q1.csv reads reports/q1.csv, and a
prefix argument to list_files is appended rather than replacing it. Leave
it blank to expose the whole bucket. Note that this scopes what the tool
functions address, not what the credentials are permitted to read — use IAM for
an enforced boundary.
Max Download Bytes
The ceiling, in bytes, on a single download_file call; the default is
52,428,800 (50 MiB). The node checks the object's reported size before
downloading and re-checks the file's actual size afterwards, in case the object
changed in between, so an oversized object cannot land on disk. Both checks
return an error naming the object's size and the configured limit. Raise it
when the agent legitimately needs larger objects and the engine host has the
disk for them; lower it to keep an agent from consuming host disk on a bucket
of large files.
Authentication
The node uses the shared RocketRide Google Cloud credentials fields and
requests the read-only Cloud Storage scope
(https://www.googleapis.com/auth/devstorage.read_only). Two authentication
types are available:
- Application Default Credentials (the default) — no key is configured and
credentials are discovered from the environment. Use this when the engine
runs on Google Cloud with an attached service account, or where
gcloudapplication-default credentials are already present. - Service Account JSON — upload the service account's JSON key file. The key is a secret; the field is stored as an uploaded file.
Project ID is optional in both modes. Left blank, it is taken from the service account key or from the ambient credentials. The identity needs permission to read the configured bucket and to list its objects; the startup bucket check will fail otherwise.
Limitations
The node declares the noremote capability, so it runs on the local engine
host and is not available for remote execution. That host needs network access
to Google Cloud Storage and enough disk for the largest download Max Download
Bytes allows. Downloaded objects are written to the engine host's temporary
directory and are only reachable by whatever runs there — the tool returns a
local path, not a URL. Access is read-only: there is no write, upload, or
delete path in this node.
Upstream docs
- Google Cloud Storage documentation
google-cloud-storagePython client- Application Default Credentials
Schema
| Field | Type | Description | Default |
|---|---|---|---|
gcs.bucketName | string | Bucket Name The Google Cloud Storage bucket name. | |
gcs.maxDownloadBytes | integer | Max Download Bytes Reject downloads larger than this many bytes (default 50 MiB). Protects server disk from oversized objects. | 52428800 |
gcs.prefix | string | Path Prefix Optional path prefix inside the bucket. | |
gcs.profile | string | "default" |
Dependencies
google-auth>=2.23.3google-cloud-storage>=2.13.0