Connect Agent Development Kit agents to Cloud Storage

You can connect your Agent Development Kit (ADK) agents to Cloud Storage. This connection enables your agents to use built-in ADK toolsets.

As an AI developer, you can integrate ADK with Cloud Storage to connect your agents to your stored data. This integration helps you scale your agentic workloads. You can use Cloud Storage to persist state, memory, and checkpoints for long-running tasks. You can also use Cloud Storage to share intermediary files across a multi-agent workflow.

This document describes the benefits of integrating Cloud Storage with ADK. It covers common use cases and the capabilities of the available toolsets. For step-by-step setup instructions and code examples, see the ADK integration guide.

Benefits of Cloud Storage integration with ADK

When you integrate Cloud Storage with your agents, they can handle large files, maintain conversation history, and reuse your existing storage infrastructure.

  • Dynamic context expansion: Give agents access to large datasets, manuals, or media files without hitting limits on how much an LLM can read at once.
  • Durable artifact persistence: Store temporary files, logs, or generated items (like reports or images) reliably outside the conversation history.
  • Support for any artifact type: Process and generate different formats, including text, images, audio, and video, using Cloud Storage as shared storage.
  • Fine-grained access control: Control agent access to Cloud Storage precisely using IAM roles. ADK uses standard Google Cloud authentication to ensure agents have only the minimum permissions needed to access data or perform a task.

Use cases

By equipping your agents with Cloud Storage capabilities, you can address the following use cases:

  • Dynamic context retrieval, also known as Retrieval-Augmented Generation (RAG)
  • Artifact persistence and archiving
  • Large payload processing
  • Automated resource management

Dynamic context retrieval through RAG

Agents can act as researchers by discovering and reading documents in Cloud Storage to answer questions in real time. This approach is useful for internal knowledge bases or support bots.

  • Policy lookup: You can have an agent list and read the latest PDF manuals in a compliance-docs bucket to answer user queries about company policy.
  • Multi-object synthesis: You can build an agent to retrieve and combine information from multiple storage objects to synthesize a unified summary.

Artifact persistence and archiving

Save large amounts of agent-generated data reliably for human review, other systems, or auditing.

  • Automated reporting: You can create an agent that analyzes database metrics, generates a summarized report, and uploads it to a reports-archive bucket.
  • Store generated media: You can configure a multi-agent system to save generated images or audio objects to Cloud Storage and return only the storage URI or a signed URL.

Large payload processing

Design agents to use storage URIs (file paths) instead of pasting full file content into the chat. This avoids the high cost and inefficiency of sending large CSVs or codebases to the LLM.

  • Data pipeline handlers: You can have your agent receive a storage URI instead of consuming a large CSV. The agent can then perform analysis by processing chunks or inspecting metadata and return a summary dashboard.
  • Decoupled workflows: You can design an agent to act as a supervisor that receives a storage URI for a Cloud Storage prefix, folder, or bucket. The agent can pass this URI to backend workers to process the objects and write the final results back to storage. This pattern is compatible with event-driven services such as Cloud Run functions or Cloud Run to process data asynchronously.

Automated resource management

Agents can help optimize storage usage, automate administrative tasks, and enforce governance across multiple buckets. This is particularly useful for teams managing extensive storage infrastructure.

  • Infrastructure auditing: You can create an agent to scan bucket configurations (such as location or storage class) and suggest optimizations or identify non-compliant settings.
  • Resource cleanup: You can build an agent to identify empty or stale buckets and automate the cleanup process based on your retention policies.

ADK toolsets for Cloud Storage

ADK provides the following toolsets in Python for Cloud Storage. Understanding both helps you define agent roles and restrict their permissions.

GCSToolset for data management

The GCSToolset toolset allows your agent to manipulate files within existing buckets. Use it for tasks like reading documents, uploading results, or deleting temporary objects.

  • Read objects: Retrieve content directly using get_object_data.
  • Discover content: List available objects using list_objects.
  • Inspect object properties: Check object size or the Content-Type metadata using get_object_metadata.
  • Upload and persist: Create new objects using create_object.
  • Remove objects: Remove temporary objects using delete_objects.

GCSAdminToolset for infrastructure

Use GCSAdminToolset toolset to manage storage infrastructure, such as creating buckets or automating administrative tasks.

  • Discover infrastructure: List buckets in a project using list_buckets.
  • Provision storage: Create new buckets using create_bucket.
  • Reconfigure storage: Modify configurations using update_bucket.
  • Deprovision storage: Remove buckets using delete_bucket.
  • Inspect bucket context: Get bucket metadata using get_bucket to check bucket location, storage class, or access controls.

Best practices

To optimize agent performance and security when integrating with Cloud Storage, consider the following best practices:

  • Decouple large payloads from conversation history: Avoid passing large files directly to the agent. Store them in Cloud Storage and send file references (URIs) instead. This reduces token costs and prevents hitting context limits.
  • Apply the principle of least privilege: Give the agent only the minimum permissions needed to perform its tasks. Avoid broad roles like roles/storage.admin unless managing infrastructure. For standard file operations, use targeted roles like roles/storage.objectUser or roles/storage.objectViewer restricted to specific buckets.
  • Manage configurations centrally: Avoid hardcoding bucket names or object name paths in your agent logic. Use environment variables or configuration managers to switch between development, testing, and production storage environments.
  • Implement efficient retrieval strategies: When using Cloud Storage as a layer for knowledge retrieval, don't load entire large documents into the agent's context. Pre-process and chunk documents, or use dedicated search tools to retrieve only the relevant segments.

Limitations

When integrating Cloud Storage with ADK, keep the following limitations in mind:

  • Immutable objects: Cloud Storage objects are immutable. You can't append data to an existing object. If your agent needs to log events continuously to a single file, then it must overwrite the object completely or create multiple small objects and compose the objects later.
  • Latency in high-frequency state management: Cloud Storage is well-suited for durable artifact storage and large payloads. However, using Cloud Storage for high-frequency and low-latency state updates can introduce latency. For example, tracking every turn in a rapid conversation exchange might be slower than using in-memory caches or databases.
  • Lack of multi-object atomicity: Cloud Storage operations apply to individual objects. If your agent requires atomic updates across multiple files simultaneously, then you must implement coordination logic within your application.

What's next

To see detailed code examples, setup instructions, and parameter references to initialize the Cloud Storage toolsets in your Python application, see ADK integration guide.