# JSON files as a database on Google Cloud Storage (GCS) (/database/providers/gcs/overview)



Agno supports using [Google Cloud Storage (GCS)](https://cloud.google.com/storage) 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](https://cloud.google.com/docs/get-started).

## Usage [#usage]

<Steps>
  <Step title="Install dependencies and configure the model">
    Use a [virtual environment](/sdk/setup):

    ```bash
    uv pip install -U agno google-auth google-cloud-storage openai ddgs
    export OPENAI_API_KEY="your-openai-api-key"
    ```
  </Step>

  <Step title="Choose an existing bucket">
    The examples use `GCS_BUCKET_NAME`. Create a bucket once using the [Google Cloud bucket setup guide](https://cloud.google.com/storage/docs/creating-buckets), 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.

    ```bash
    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.
  </Step>

  <Step title="Configure real GCS authentication">
    For local development, install the [Google Cloud CLI](https://cloud.google.com/sdk/docs/install), select your project, and configure Application Default Credentials:

    ```bash
    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.
  </Step>
</Steps>

### Local Testing with Fake GCS [#local-testing-with-fake-gcs]

To use [fake-gcs-server](https://github.com/fsouza/fake-gcs-server), prepare a preloaded bucket before starting the server:

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

Save as `compose.yaml`:

```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:

```bash
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.

```python title="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 [#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](/database/providers/gcs/usage/gcs-for-agent).
