GCS File System (Beta)

Estimated reading: 12 minutes

The GCS File System component manages objects in Google Cloud Storage (GCS) from within a workflow. It supports uploading, downloading, listing, checking, deleting, copying, and moving objects. It also supports creating folder-like paths, retrieving object metadata, and generating temporary signed URLs. The available input fields change based on the selected operation.

Prerequisites

Before configuring the GCS File System component, ensure you have the following:

a. An active Google Cloud Platform (GCP) project with the Cloud Storage API enabled.
b. A valid GCP Service Account JSON key file or JSON payload, or Application Default Credentials (ADC) configured in your runtime environment.
c. The target GCS bucket and object paths accessible to the configured service account.
d. The necessary IAM permissions for the service account to perform the intended operations on the target bucket and objects.

Note: Handle credentials securely. Do not expose Service Account JSON keys, private keys, client emails, or access tokens through Agent tool inputs, outputs, or logs.

Parameters

Parameter Description
Operation* Specifies the Google Cloud Storage operation to perform. Available operations include List, Upload, Download, Exists, Delete, Move, Copy, Create Folder, Get Metadata, and Generate Signed URL.
GCP Service Account JSON* Uploads the GCP Service Account JSON key file used to authenticate API calls and sign URLs. Required when using Service Account Key authentication. Keep this value secure.

Refer: Get the Service Account JSON
GCP Project ID Specifies the GCP Project ID used for billing and API calls.
Data Inputs Connects the node to provide the data (Data, DataFrame, or JSON) to upload to GCS. Displayed only when Upload is selected.
File Path(s) Specifies one or more server-side file paths of the files to upload. Enter each path on a separate line. Displayed only when Upload is selected.
Select File(s) Specifies the files selected for upload. Displayed only when Upload is selected.
Strategy for File Upload Specifies how files are uploaded to GCS. Store Data uploads parsed file content, while Store Original File uploads the original file without modifying its contents. Displayed only when Upload is selected.
Content Specifies text to save as the file's content, or connects a Message, Data, JSON, or DataFrame input when no file is given. Displayed only when Upload is selected.
Content File Name Specifies the file name (without extension) to save the Content as when no file is given. Displayed only when Upload is selected.
Content File Extension Specifies the file extension to use when saving Content, such as csv, docx, html, json, pdf, txt, xlsx, or xml. Displayed only when Upload is selected.
File Type Specifies the file type associated with the download (default or kb). Displayed only when Download is selected.
GCS Path Specifies the full GCS URI of the object, folder, or bucket to access, such as gs://claims/documents/2026/october/report.pdf. Displayed when List, Download, Exists, Delete, or Get Metadata is selected.
GCS Folder Path Specifies the virtual folder or directory path to create in GCS, such as gs://claims/documents/2026/. Displayed only when Create Folder is selected.
Source GCS Path Specifies the GCS path of the object or folder to move or copy. Displayed when Move or Copy is selected.
Destination GCS Path Specifies the GCS path where an object or folder is uploaded, moved, or copied. Displayed when Upload, Move, or Copy is selected.
List Max Keys Specifies the maximum number of items to return per listing request. The default value is 1000. Specify 0 to return all available results.
List Include Folders Determines whether virtual folder prefixes are returned alongside objects during List. Default: Enabled.

Disabled - Only individual object keys are returned; virtual folder prefixes are omitted.
Enabled - Virtual folder prefixes are included alongside objects in the listing output.
Upload Overwrite Determines whether an existing object at the destination can be replaced during Upload. Default: Enabled.

Disabled - Existing objects are preserved and the upload fails if the destination path already exists.
Enabled - Existing objects at the destination path are overwritten with the newly uploaded content.
Delete Recursive Determines whether all objects under a folder prefix are deleted recursively. Default: Disabled.

Disabled - Only the exact target object or empty folder marker is deleted.
Enabled - All objects under the specified prefix are deleted recursively in batches.
Move Overwrite Determines whether an existing object at the destination can be replaced during Move. Default: Enabled.

Disabled - Existing destination objects remain unchanged and the move operation does not overwrite them.
Enabled - Existing destination objects are replaced before the source object is deleted.
Move Recursive Determines whether all objects within a folder prefix are moved recursively. Default: Enabled.

Disabled - Only the specified object is moved.
Enabled - All objects within the specified folder prefix are moved recursively to the destination.
Copy Overwrite Determines whether an existing object at the destination can be replaced during Copy. Default: Enabled.

Disabled - Existing destination objects remain unchanged and the copy operation does not overwrite them.
Enabled - Existing destination objects are overwritten by the copied object.
Copy Recursive Determines whether all objects within a folder prefix are copied recursively. Default: Enabled.

Disabled - Only the specified object is copied.
Enabled - All objects within the specified folder prefix are copied recursively.
Timeout (Seconds) Specifies the maximum time the operation can run before timing out. The default value is 30.
Retry Count Specifies the number of automatic retry attempts if a transient operation fails. The default value is 1.
Delay Between Retries (Seconds) Specifies the wait time between consecutive retry attempts. The default value is 1.
Delay Before Execution (Seconds) Specifies how long to wait before the component starts processing. The default value is 0.
Delay After Execution (Seconds) Specifies how long to wait after the component finishes processing. The default value is 0.
Continue on Error Determines how the workflow proceeds when an unrecoverable error occurs.

Stop Workflow - Halts workflow execution.
Continue - Skips this step and continues without passing the error downstream.
Continue Using Error Output - Continues execution and routes error details through the error output handle.

Strategy for File Upload

The Strategy for File Upload parameter determines how the component handles files during an upload operation.

Store Data: Uploads the parsed text content of the source file.
Store Original File: Uploads the original file without modifying its contents.

For example, when uploading a PDF file, Store Data uploads its parsed text content, whereas Store Original File uploads the original PDF. Choose the strategy according to whether the workflow requires the extracted content or the original file.

Data Input Format and Upload Priority

When multiple upload inputs are connected, the component resolves the upload source in the following priority order:

Data Inputs (Data / DataFrame / JSON) → File Path(s) → Select File(s)

Store Data: Uploads the parsed text content of the input file. The input must be in a format supported by the component’s file-processing functionality.
Store Original File: Uploads the original file without modifying its contents. Use File Path(s) or Select File(s) to specify the files to upload.
Content Upload: When no file is provided, use Content along with Content File Name and Content File Extension to save text or structured data directly as a file in GCS.

Large files automatically use GCS resumable uploads for reliability, and Download streams large objects directly to disk. Supported input fields also accept Global Variables.

File Path(s)

Specifies one or more server-side file paths to upload to Google Cloud Storage. Enter each file path on a separate line; do not use commas to separate paths.

Example:
/app/RobilityFlow/Staticfiles/reports/report.pdf
/app/RobilityFlow/Staticfiles/data/input.csv

Use this field with the Store Original File strategy.

Supported Operations

Operation Description
List Retrieves the objects available under the specified GCS bucket or prefix, with support for pagination and result limits. Enable List Include Folders to include virtual folder prefixes.
Upload Uploads files or data to the specified GCS destination. The upload behavior depends on the selected Strategy for File Upload and Upload Overwrite settings.
Download Downloads an object from the specified GCS path to a local file output reference or path, streaming large objects to disk.
Exists Checks whether the specified GCS path exists and identifies whether it represents an object, folder, or bucket.
Delete Deletes the specified GCS object. Enable Delete Recursive to delete all objects under a folder prefix in batches.
Move Moves an object or virtual folder to the destination. The operation performs a server-side copy/rewrite followed by a source delete once the copy succeeds. It returns a partial-failure response if source deletion fails after the copy completes.
Copy Copies an object or virtual folder to another GCS location using server-side rewrite while retaining the original object.
Create Folder Creates a virtual folder marker (folder/) in standard flat buckets or a native directory in Hierarchical Namespace (HNS) enabled buckets.
Get Metadata Retrieves normalized metadata for a single object, such as its name, size, content type, last-modified timestamp, ETag, generation, storage class, and custom metadata.

Outputs

The component provides outputs according to the selected operation and the result returned by Google Cloud Storage.

Output Description
Result Returns a standardized JSON envelope containing success, operation, path (where applicable), data, and message.
DataFrame Returns structured tabular results for operations that support this output, such as objects or metadata returned by List.
Message Returns a formatted text message indicating the operation status, path, or error details.

The available output content depends on the selected operation. Use the relevant output when configuring subsequent workflow steps.

Standardized JSON Output Structure

Every operation returns a consistent response structure in the Result output:

{
  "success": true,
  "operation": "exists",
  "path": "gs://claims/documents/report.pdf",
  "data": {
    "exists": true,
    "type": "object"
  },
  "message": "Path exists"
}

When an operation fails (for example, bucket not found, permission denied, or an object already exists while overwrite is disabled), success is set to false, data is empty, and message provides a clear, actionable error description without exposing sensitive credentials.

Required IAM Permissions

The GCP Service Account or ADC identity must have the IAM permissions required to perform the selected operation on the target bucket and objects.

Operation Required Permissions / Roles
List storage.objects.list (for example, roles/storage.objectViewer)
Upload storage.objects.create, and storage.objects.delete if overwriting (for example, roles/storage.objectAdmin)
Download storage.objects.get (for example, roles/storage.objectViewer)
Exists storage.objects.get and storage.objects.list (or storage.buckets.get for bucket checks)
Delete storage.objects.delete (and storage.objects.list for recursive prefix deletion)
Create Folder storage.objects.create (for example, roles/storage.objectAdmin)
Get Metadata storage.objects.get (for example, roles/storage.objectViewer)
Copy storage.objects.get on the source and storage.objects.create on the destination
Move storage.objects.get and storage.objects.delete on the source, and storage.objects.create on the destination

Tool Mode

Tool Mode enables the GCS File System component to expose its supported Google Cloud Storage operations as tools for an Agent. Based on the task requirements, the Agent can select and invoke one or multiple available actions during execution without accessing authentication credentials.

Available Actions

Action Description
gcs_list Lists objects and folders in a specified GCS bucket or prefix with automatic page-token pagination.
gcs_upload Uploads data or files to a specified gs:// destination location with optional overwrite control.
gcs_download Downloads an object from GCS and returns the local file reference or path for further processing.
gcs_exists Checks whether a specified object, folder, or bucket exists in GCS.
gcs_delete Deletes a specified object or prefix from GCS. Supports optional recursive deletion.
gcs_move Moves an object from one GCS location to another safely using a copy-then-delete workflow.
gcs_copy Copies an object to another GCS location using server-side rewrite while preserving the original.
gcs_create_folder Creates a virtual folder or Hierarchical Namespace (HNS) directory in a specified GCS location.
gcs_get_metadata Retrieves normalized metadata for an object in a specified GCS location.

How Tool Mode Helps

When Tool Mode is enabled, the Agent can choose the appropriate GCS action or combine multiple actions to complete a task.

For example, it can verify whether an object exists (gcs_exists) or inspect its size and type (gcs_get_metadata) before downloading a file, upload generated reports (gcs_upload), to share files securely, or organize processed files into folders (gcs_move and gcs_create_folder).

Note: Toggle Tool Mode on in the component toolbar to make the supported actions available to the Agent. Configure the required authentication settings (GCP Service Account JSON and GCP Project ID) in the component. The Agent can use the available tools according to the configured component settings and permissions.

Behavior Example

Move an Object Between GCS Locations

Set Operation to Move, Source GCS Path to gs://claims/incoming/sales.xlsx, and Destination GCS Path to gs://claims/archive/sales.xlsx.

Move Overwrite Disabled: If archive/sales.xlsx already exists, the existing object remains unchanged and the source object stays in incoming/.
Move Overwrite Enabled: If the operation succeeds, the destination object is replaced and the source object is removed after the copy completes.

Always verify the operation result before using the destination object in subsequent workflow steps.

Troubleshooting

Issue What to Check
Authentication / Invalid JSON Error Verify that the uploaded GCP Service Account JSON file is valid, uncorrupted, and belongs to an active service account whose key has not been revoked.
Permission Denied (403) Ensure the service account has the required IAM permissions on the target bucket, such as storage.objects.get, storage.objects.create, storage.objects.delete, or iam.serviceAccounts.signBlob for signed URLs.
Bucket or Object Not Found (404) Confirm the path uses the format gs://<bucket>/<object> and verify spelling and casing, as GCS object names are case-sensitive.
Upload Blocked by Existing Object Check the Upload Overwrite parameter. When disabled, GCS rejects uploads to paths that already exist.
Signed URL Generation Fails Signed URLs require a Service Account key with private-key signing capability (or the Service Account Token Creator role when using impersonation or ADC). Also verify that the requested expiry does not exceed 7 days.
Incomplete Object Listing Check List Max Keys (default 1000; set to 0 for no limit) or verify whether List Include Folders is filtering or grouping results by "/" delimiters.
Share this Doc

GCS File System (Beta)

Or copy link

CONTENTS
Robility Chatbot
Robility Assistant
Online