Google Cloud Storage

Bucket-scoped state store for PraisonAI agents on GCS

Store agent state in a Google Cloud Storage bucket — cheap, durable, and fully wired to the StateStore contract.

Setup

pip install google-cloud-storage
export GOOGLE_APPLICATION_CREDENTIALS=path/to/service-account.json

Quick Start

1. Enable via memory config

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

   from praisonaiagents import Agent
   
   agent = Agent(
       name="Assistant",
       instructions="You are a helpful assistant.",
       memory={
           "backend": "gcs",
           "db": "gs://your-bucket/state",
           "session_id": "my-session"
       }
   )
   
   response = agent.start("Hello!")
   print(response)

2. Use the store directly

   GCSStateStore now instantiates and covers the full StateStore protocol.

   from praisonai.persistence.state.gcs import GCSStateStore
   
   store = GCSStateStore(
       bucket_name="your-bucket",
       prefix="state/",
       credentials_path="path/to/service-account.json",
   )
   
   store.set("user:42", {"name": "Ada", "plan": "pro"})
   print(store.get("user:42"))      # {'name': 'Ada', 'plan': 'pro'}
   print(store.keys("user:*"))      # ['user:42']
   store.close()

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.

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

Related