GCS Media Storage

Offload attached and generated media to Google Cloud Storage and store references after successful uploads.

AgentOS uploads byte-backed media to Google Cloud Storage and replaces successfully offloaded content with a MediaReference. Provider-managed files are skipped; URL-only media is not downloaded unless persist_remote_urls is enabled. If an upload fails, AgentOS logs the failure and retains the original media, which can still be stored in the database.

gcs_media_storage.py
"""
Google Cloud Storage Media Storage
==================================

Demonstrates keeping media bytes out of the database. AgentOS sends attached and
generated files to Google Cloud Storage and persists only a MediaReference.

Set AGNO_FILE_OUTPUT_GCS_BUCKET to the destination bucket. Authenticate with
Application Default Credentials or set GOOGLE_APPLICATION_CREDENTIALS to a
service-account JSON file.

Prerequisites: OPENAI_API_KEY, Google Cloud credentials, and pip install 'agno[gcs]'
Run: .venvs/demo/bin/python cookbook/05_agent_os/02_databases/gcs_media_storage.py
Try: Attach an image or CSV and ask about it, then ask the agent to generate a CSV
"""

import os

from agno.agent import Agent
from agno.db.sqlite import SqliteDb
from agno.media.storage.gcs import AsyncGCSMediaStorage
from agno.models.openai import OpenAIResponses
from agno.os import AgentOS
from agno.tools.file import FileGenerationTools
from dotenv import load_dotenv

load_dotenv()

# ---------------------------------------------------------------------------
# Create Database and Media Storage
# ---------------------------------------------------------------------------

bucket = os.getenv("AGNO_FILE_OUTPUT_GCS_BUCKET")
if not bucket:
    raise ValueError(
        "AGNO_FILE_OUTPUT_GCS_BUCKET must be set to the destination GCS bucket"
    )

db = SqliteDb(db_file="tmp/agentos_gcs_media_storage.db")
storage = AsyncGCSMediaStorage(
    bucket=bucket,
    project=os.getenv("GCP_PROJECT"),
    credentials_path=os.getenv("GOOGLE_APPLICATION_CREDENTIALS"),
    prefix="agno/agentos/files/",
    presigned_url_expiry=3600,
)

# ---------------------------------------------------------------------------
# Create Agent
# ---------------------------------------------------------------------------

file_agent = Agent(
    id="gcs-media-storage-agent",
    name="GCS Media Storage Agent",
    model=OpenAIResponses(id="gpt-5.5"),
    db=db,
    media_storage=storage,
    store_media=True,
    add_history_to_context=True,
    tools=[FileGenerationTools(all=True)],
    description="Analyze uploaded media and generate files stored in GCS.",
    instructions=[
        "Read and answer questions about attached media and files.",
        "Use the appropriate file-generation tool when the user requests an output file.",
        "Always use a descriptive filename with the correct extension.",
        "Briefly explain what you read or generated.",
    ],
    markdown=True,
)

# ---------------------------------------------------------------------------
# Create AgentOS
# ---------------------------------------------------------------------------

agent_os = AgentOS(
    id="agentos-gcs-media-storage",
    name="AgentOS GCS Media Storage",
    agents=[file_agent],
    db=db,
    media_storage=storage,
)
app = agent_os.get_app()

# ---------------------------------------------------------------------------
# Run AgentOS
# ---------------------------------------------------------------------------

if __name__ == "__main__":
    agent_os.serve(app="gcs_media_storage:app", reload=True)

Run the Example

Set up your virtual environment

uv venv --python 3.12
source .venv/bin/activate

Install dependencies

uv pip install -U "agno[gcs,os]" openai python-docx python-dotenv reportlab

Export environment variables

export AGNO_FILE_OUTPUT_GCS_BUCKET="your_agno_file_output_gcs_bucket_here"
export GCP_PROJECT="your_gcp_project_here"
export OPENAI_API_KEY="your_openai_api_key_here"

Authenticate with Google Cloud

Use an existing bucket and an identity with permission to read, write, and delete its objects. The example does not create the bucket. Choose one credential method:

Local Application Default Credentials: remove GOOGLE_APPLICATION_CREDENTIALS from any .env file, clear it in the server terminal, then sign in:

unset GOOGLE_APPLICATION_CREDENTIALS
gcloud auth application-default login

Service-account JSON: set GOOGLE_APPLICATION_CREDENTIALS to the absolute path of an existing service-account JSON file in the server environment. For example:

export GOOGLE_APPLICATION_CREDENTIALS="/absolute/path/service-account.json"

This example passes that path explicitly to the storage adapter, so it takes precedence over local ADC login credentials.

Run the example

Save the code above as gcs_media_storage.py, then run:

python gcs_media_storage.py

Full source: cookbook/05_agent_os/02_databases/gcs_media_storage.py