Google Cloud Storage Service

Purpose

The Google Cloud Storage (GCS) Service provides a scalable, durable, and versioned backend implementation of the artifact storage interface within the broader Artifact Management topic. It addresses the need to persist and retrieve artifacts—binary blobs or files—across sessions and users using Google Cloud's object storage infrastructure. Unlike the in-memory backend, which is ephemeral and suitable for testing, the GCS Service enables persistent, multi-versioned artifact storage with scoped naming conventions that organize artifacts by application, user, session, and filename.

This subtopic ensures that artifacts are reliably stored with explicit versioning, allowing agents and workflows to load specific or the latest versions, list available artifacts, and delete them either individually or in bulk. The versioning and naming semantics are critical for maintaining data integrity and enabling multi-user, multi-session support within the system.

Functionality

Scoped Naming and Versioning

Artifacts are stored in GCS buckets using a hierarchical naming convention that scopes blobs by:

Application Name
User ID
Session ID (optional for user-scoped artifacts)
Filename
Version Number

The naming logic distinguishes between session-scoped and user-scoped artifacts. For example:

Session-scoped blob name:

{appName}/{userID}/{sessionID}/{fileName}/{version}

User-scoped blob name (for filenames prefixed with "user:"):
```
{appName}/{userID}/user/{fileName}/{version}
```

This ensures that user-global artifacts are separated from session-specific ones, supporting flexible artifact lifecycles.

Version Management

When saving an artifact, the service queries existing versions and auto-increments to create a new version.
Loading an artifact without specifying a version defaults to the latest available version.
Listing artifacts aggregates filenames from both session and user scopes.
Deletion supports removing a single version or all versions of an artifact.

Core Methods

Save: Validates the request, determines the next version, constructs the blob name, writes the content to GCS with appropriate MIME type, and returns the new version number.
Load: Retrieves the specified version or the latest version of the artifact, streams the content as a genai.Part, and handles GCS errors such as object non-existence.
Delete: Deletes a specific version or all versions of an artifact in parallel, handling concurrency with Go's errgroup.
List: Enumerates filenames available under both session and user prefixes, consolidating results without duplicates.
Versions: Returns all versions available for a given artifact, ensuring existence before access.

Client Abstraction and Testing

The service uses interface abstractions (gcsClient, gcsBucket, gcsObject, etc.) to wrap the real GCS client, enabling mocking for unit tests. The gcs_test.go file demonstrates an in-memory fake client implementation that mimics the GCS interfaces, supporting thorough testing without external dependencies.

Example snippet showing version-aware save logic:

response, err := s.versions(ctx, &artifact.VersionsRequest{
    AppName: req.AppName, UserID: req.UserID, SessionID: req.SessionID, FileName: req.FileName,
})
nextVersion := int64(1)
if len(response.Versions) > 0 {
    nextVersion = slices.Max(response.Versions) + 1
}
blobName := buildBlobName(appName, userID, sessionID, fileName, nextVersion)
writer := s.bucket.object(blobName).newWriter(ctx)
// Write data...

This snippet highlights how the service determines the next version and writes a new artifact blob.

Integration

The GCS Service implements the artifact.Service interface defined in the Artifact Management topic, seamlessly substituting or complementing the in-memory backend. Agents, tools, and session components interact with this service for artifact persistence when durable storage is required.

By enforcing scoped naming and versioning, the GCS Service supports multi-user, multi-session workflows, enabling agents to reliably load the correct artifact versions for their context. It integrates with tooling such as the LoadArtifactsTool (referenced in the project overview) that dynamically injects artifact content into LLM prompts.

Testing and development workflows benefit from the mocked client abstraction, ensuring reliability without requiring actual GCS access during local builds or CI runs.

Diagram

flowchart TD
UserAgent -->|Save Artifact| GCSService[Google Cloud Storage Service]
GCSService --> GCSBucket[GCS Bucket]
GCSBucket --> GCSObject[Blob Object with Version]
UserAgent -->|Load Artifact| GCSService
GCSService -->|List / Versions| GCSBucket
GCSService -->|Delete Artifact| GCSBucket
Note[Blob Naming: app/user/session/filename/version]
GCSService --- Note

This flowchart illustrates the interaction between user agents and the GCS Service, showing how artifact save, load, list, and delete operations map to the underlying GCS bucket and versioned blob objects with scoped naming conventions.