Skip to main content
Store agent state in a Google Cloud Storage bucket — cheap, durable, and fully wired to the StateStore contract.
GCS state store is fully functional as of PraisonAI PR #5332. Earlier releases raised TypeError: Can't instantiate abstract class GCSStateStore with abstract methods expire, hdel, hget, hgetall, hset, keys, ttl before any GCS call. GCSStateStore now implements the complete StateStore protocol.

Setup

Quick Start

1

Enable via memory config

Point an agent at a bucket path — persistence is automatic.
2

Use the store directly

GCSStateStore now instantiates and covers the full StateStore protocol.

Supported Operations

GCSStateStore covers every method on the StateStore ABC end-to-end. Scalars round-trip because non-dict values are wrapped internally as {"__value__": ...} and unwrapped on get(), so set() matches the ABC (Any -> None) and get() returns Optional[Any]. TTL expiry survives hash rewrites — hset / hdel / expire carry the existing expiry through the read-modify-write. hdel returns the count of fields actually removed; a failed rewrite reports 0 rather than falsely claiming success.
GCS hash ops are a read-modify-write of one JSON blob per key, not field-atomic. For high-contention field-level concurrency, prefer Firestore or Redis.

When to Choose GCS

Pick GCS for cheap, bucket-scoped state on a Cloud Run or GKE deployment where you already have a bucket and want durable state without running a separate database. Not the right tool for high-concurrency hash updates — reach for Firestore or Redis there.

Best Practices

Set GOOGLE_APPLICATION_CREDENTIALS to your service-account JSON, or pass credentials_path= explicitly. On Cloud Run / GKE, the attached service account is picked up automatically.
Give each environment its own prefix (prod/state/, staging/state/) so keys never collide inside one bucket.
Each hset / hdel rewrites the whole JSON blob for a key. Concurrent writers to different fields of the same key can lose updates — use Firestore or Redis for field-level concurrency.

Firestore

Field-atomic state store for high-concurrency updates.

Persistence Overview

How state, conversation, and knowledge stores fit together.