GCS for Agent

Agno supports using Google Cloud Storage (GCS) as a storage backend for Agents using the GcsJsonDb class. This storage backend stores session data as JSON blobs in a GCS bucket.

Usage

Configure your agent with GCS storage to enable cloud-based session persistence.

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
from agno.tools.websearch import WebSearchTools

# 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,
)

# Initialize the Agno agent with the new storage backend and a web search tool.
agent1 = Agent(
    db=db,
    tools=[WebSearchTools()],
    add_history_to_context=True,
    debug_mode=False,
)

# Execute sample queries.
agent1.print_response("How many people live in Canada?")
agent1.print_response("What is their national anthem called?")

# Create a new agent and make sure it pursues the conversation
agent2 = Agent(
    db=db,
    session_id=agent1.session_id,
    tools=[WebSearchTools()],
    add_history_to_context=True,
    debug_mode=False,
)

agent2.print_response("What's the name of the country we discussed?")
agent2.print_response("What is that country's national sport?")

Prerequisites

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.

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.

Run the Example

Save the code as gcs_for_agent.py, complete the prerequisites above, then run:

python gcs_for_agent.py