docs/en/integrations/cloud-storage/tools/cloud-storage-download-object.md
A cloud-storage-download-object tool streams a Cloud Storage object to a local
file on the Toolbox server. Unlike cloud-storage-read-object, it does not
return the object bytes to the LLM and does not require UTF-8 text content, so it
can be used for binary objects or large files.
The destination path is interpreted on the server where Toolbox is running.
By default, destination must be an absolute path and paths containing .. are
rejected. When destination_dir is configured on the tool, destination remains
visible to the LLM but must be a relative path under that configured directory.
Absolute paths and paths that escape destination_dir are rejected.
{{< compatible-sources >}}
The Cloud Storage credentials must be able to read the object. The Toolbox
server process must also be able to create or overwrite the destination file.
When overwrite is false, the tool returns an agent-fixable error if the
destination already exists.
| parameter | type | required | description |
|---|---|---|---|
| bucket | string | true | Name of the Cloud Storage bucket containing the object. |
| object | string | true | Full object name (path) within the bucket, e.g. path/to/file.txt. |
| destination | string | true | Absolute local filesystem path where the object will be written. Relative paths and paths containing .. are rejected. |
| overwrite | boolean | false | If true, overwrite the destination when it already exists. If false (default), return an error when it exists. |
If bucket is configured on the tool, it is removed from the parameter list. If
destination_dir is configured on the tool, destination stays in the parameter
list but changes to a relative path under destination_dir. If overwrite is
configured on the tool, it is removed from the parameter list.
kind: tool
name: download_object
type: cloud-storage-download-object
source: my-gcs-source
description: Use this tool to download a Cloud Storage object to the server filesystem.
kind: tool
name: download_reports
type: cloud-storage-download-object
source: my-gcs-source
description: Use this tool to download report objects into the reports directory.
bucket: analytics-exports
destination_dir: /var/toolbox/downloads/reports
overwrite: false
The tool returns a JSON object with:
| field | type | description |
|---|---|---|
| destination | string | Local path where the object was written. |
| bytes | integer | Number of bytes written. |
| contentType | string | Content type recorded on the Cloud Storage object. |
| field | type | required | description |
|---|---|---|---|
| type | string | true | Must be "cloud-storage-download-object". |
| source | string | true | Name of the Cloud Storage source to download objects from. |
| description | string | true | Description of the tool that is passed to the LLM. |
| bucket | string | false | Cloud Storage bucket to use for every invocation. When set, bucket is hidden from the tool parameters. |
| destination_dir | string | false | Absolute local directory to contain downloaded files. When set, destination is a relative path under this directory. |
| overwrite | boolean | false | Whether to overwrite existing destination files for every invocation. When set, overwrite is hidden from the tool parameters. |