GCS for Team

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

Usage

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

gcs_for_team.py

"""
Run: `uv pip install agno openai google-auth google-cloud-storage ddgs agno` to install the dependencies
"""

import os
import google.auth
from google.auth.credentials import AnonymousCredentials
from typing import List

from agno.agent import Agent
from agno.db.gcs_json import GcsJsonDb
from agno.models.openai import OpenAIResponses
from agno.team import Team
from agno.tools.hackernews import HackerNewsTools
from agno.tools.websearch import WebSearchTools
from pydantic import BaseModel

# 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="team/",
    project=project_id,
    credentials=credentials,
)

class Article(BaseModel):
    title: str
    summary: str
    reference_links: List[str]

hn_researcher = Agent(
    name="HackerNews Researcher",
    model=OpenAIResponses(id="gpt-5.2"),
    role="Gets top stories from hackernews.",
    tools=[HackerNewsTools()],
)

web_searcher = Agent(
    name="Web Searcher",
    model=OpenAIResponses(id="gpt-5.2"),
    role="Searches the web for information on a topic",
    tools=[WebSearchTools()],
    add_datetime_to_context=True,
)

hn_team = Team(
    name="HackerNews Team",
    model=OpenAIResponses(id="gpt-5.2"),
    members=[hn_researcher, web_searcher],
    db=db,
    instructions=[
        "First, search hackernews for what the user is asking about.",
        "Then, ask the web searcher to search for each story to get more information.",
        "Finally, provide a thoughtful and engaging summary.",
    ],
    output_schema=Article,
    markdown=True,
    show_members_responses=True,
)

hn_team.print_response("Write an article about the top 2 stories on hackernews")

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_team.py, complete the prerequisites above, then run:

python gcs_for_team.py