JSON files as a database on Google Cloud Storage (GCS)

Agno supports using Google Cloud Storage (GCS) as a database with the GcsJsonDb class. Session data will be stored as JSON blobs in a GCS bucket.

You can get started with GCS following their Get Started guide.

Usage

Install dependencies and configure the model

Use a virtual environment:

uv pip install -U agno google-auth google-cloud-storage openai ddgs
export OPENAI_API_KEY="your-openai-api-key"

Choose an existing bucket

The examples use GCS_BUCKET_NAME. Create a bucket once using the Google Cloud bucket setup guide, or ask your administrator for an existing bucket. Grant the application identity the object permissions it needs for that bucket. GcsJsonDb obtains a bucket handle; it does not create the bucket.

export GCS_BUCKET_NAME="your-existing-bucket"

Keep the bucket and prefix stable to read earlier runs. GCS JSON storage rewrites blobs; it does not provide the same concurrent-write semantics as a transactional database.

Configure real GCS authentication

For local development, install the Google Cloud CLI, select your project, and configure Application Default Credentials:

gcloud init
gcloud auth application-default login

For a service account, set GOOGLE_APPLICATION_CREDENTIALS to its credential file instead. The examples use google.auth.default() when STORAGE_EMULATOR_HOST is absent. The model still needs its own OpenAI key.

Local Testing with Fake GCS

To use fake-gcs-server, prepare a preloaded bucket before starting the server:

mkdir -p fake-gcs-data/example-gcs-bucket
echo "Local test bucket" > fake-gcs-data/example-gcs-bucket/seed.txt

Save as compose.yaml:

services:
  fake-gcs-server:
    image: fsouza/fake-gcs-server:latest
    ports:
      - "127.0.0.1:4443:4443"
    command: ["-scheme", "http", "-port", "4443", "-public-host", "localhost:4443"]
    volumes:
      - ./fake-gcs-data:/data

Start Docker Compose and point the example at the local bucket:

docker compose up -d
export STORAGE_EMULATOR_HOST="http://localhost:4443"
export GCS_BUCKET_NAME="example-gcs-bucket"
python gcs_for_agent.py

Use the filename from the Team or Workflow page when running those examples. Their explicit emulator branch supplies AnonymousCredentials and project="local-test", so it does not call google.auth.default(). The emulator is for local storage tests; model and web-search calls still use their real services.

gcs_for_agent.py

import os
import google.auth
from google.auth.credentials import AnonymousCredentials
from agno.agent import Agent
from agno.db.gcs_json import GcsJsonDb

# Local emulator uses anonymous credentials; real GCS uses configured ADC.
if os.environ.get("STORAGE_EMULATOR_HOST"):
    credentials, project_id = AnonymousCredentials(), "local-test"
else:
    credentials, project_id = google.auth.default()

# The bucket must already exist. Keep this name stable across restarts.
bucket_name = os.environ["GCS_BUCKET_NAME"]

db = GcsJsonDb(
    bucket_name=bucket_name,
    prefix="agent/",
    project=project_id,
    credentials=credentials,
)

# Setup your Agent with the Database
agent = Agent(db=db)

Params

Parameter	Type	Default	Description
`id`	`Optional[str]`	-	Database ID. Derived deterministically from bucket, project and prefix when omitted.
`bucket_name`	`str`	-	Name of the GCS bucket where JSON files will be stored.
`prefix`	`Optional[str]`	-	Path prefix for organizing files in the bucket. Defaults to "agno/".
`session_table`	`Optional[str]`	-	Name of the JSON file to store sessions (without .json extension).
`runs_table`	`Optional[str]`	`None`	Storage name for individual runs. Defaults to `agno_runs`, or `<session_table>_runs` when a custom session name is supplied.
`memory_table`	`Optional[str]`	-	Name of the JSON file to store user memories.
`metrics_table`	`Optional[str]`	-	Name of the JSON file to store metrics.
`eval_table`	`Optional[str]`	-	Name of the JSON file to store evaluation runs.
`knowledge_table`	`Optional[str]`	-	Name of the JSON file to store knowledge content.
`traces_table`	`Optional[str]`	-	Name of the JSON file to store traces.
`spans_table`	`Optional[str]`	-	Name of the JSON file to store spans.
`project`	`Optional[str]`	-	GCP project ID. If None, uses default project.
`credentials`	`Optional[Any]`	-	GCP credentials. If None, uses default credentials.

See the full example here.