Artifact Management

Overview

Artifact Management provides a unified service interface and implementations for handling artifacts—files or blobs—within the system. Artifacts are stored, retrieved, listed, versioned, and deleted with strong support for version control and multi-tenant isolation based on application name, user ID, and session ID. The system is designed to support multiple backend storage implementations, primarily an in-memory store for testing and a Google Cloud Storage (GCS) backend for production use.

This module's primary goal is to facilitate reliable, versioned persistence of arbitrary binary or textual data ("artifacts") associated with user-agent sessions and applications. It enables agents and tools to save and retrieve content such as files, images, or any data blobs during AI workflows.

Core Concepts

Artifact Identity and Versioning

Each artifact is uniquely identified by a combination of:

Artifacts also support versioning, where multiple versions of the same artifact can coexist. Saving a new artifact automatically increments the version unless explicitly overridden.

User-Scoped Artifacts

Artifacts whose filenames are prefixed with "user:" are treated as user-scoped rather than session-scoped. Such artifacts are stored under a user-level namespace, making them accessible across all sessions for that user. This distinction is important for sharing or persisting user-wide data beyond a single session.

Service Interface

The artifact.Service interface defines the core operations:

All operations require the artifact's identifying fields and provide validation to ensure completeness.

Backend Implementations

The module currently provides two main backend implementations conforming to the artifact.Service interface:

How Artifact Management Works

Saving Artifacts

When saving an artifact, the service:

  1. Validates the request fields.

  2. Determines if the file is user-scoped (filename starts with "user:").

  3. For in-memory:

    • Locks the storage map.

    • Finds the highest existing version for the artifact.

    • Increments the version and stores the artifact under a composite key encoding all identity fields plus version.

  4. For GCS:

    • Queries existing versions via listing blobs with a prefix.

    • Calculates the next version.

    • Writes the artifact content (binary or text) to a GCS blob named by the composite key and version.

  5. Returns the assigned version to the caller.

Loading Artifacts

To load an artifact, the service:

  1. Validates the request.

  2. Adjusts for user-scoped files by switching the session ID to the user namespace.

  3. If a specific version is requested, attempts to load that version.

  4. If no version specified, loads the latest version by:

    • For in-memory: scanning keys for the highest version.

    • For GCS: listing blobs under the artifact prefix and selecting the highest version.

  5. Reads the artifact content and returns it as a genai.Part, which supports both inline binary data and textual content.

Listing Artifacts

Listing artifacts returns the set of filenames stored within a session namespace, including user-scoped artifacts. The service:

Deleting Artifacts

Deletion supports two modes:

For GCS, versioned deletions are performed in parallel using goroutines, while in-memory deletions remove keys directly. Deleting non-existent artifacts is not treated as an error.

Version Enumeration

The service can list all stored versions for a given artifact. This is useful for clients to know available historical versions, enabling version-specific retrieval or management.

Interactions and Usage

Artifact Key Encoding

Both backends use a consistent encoding scheme for artifact keys to ensure ordered storage and retrieval:

This encoding ensures efficient lookup of the latest versions and range scans for listing.

Code Reference Examples

Service Interface Definition

type Service interface {
    Save(ctx context.Context, req *SaveRequest) (*SaveResponse, error)
    Load(ctx context.Context, req *LoadRequest) (*LoadResponse, error)
    Delete(ctx context.Context, req *DeleteRequest) error
    List(ctx context.Context, req *ListRequest) (*ListResponse, error)
    Versions(ctx context.Context, req *VersionsRequest) (*VersionsResponse, error)
}

Saving an Artifact in In-Memory Service

func (s *inMemoryService) Save(ctx context.Context, req *SaveRequest) (*SaveResponse, error) {
    // Validate request
    // Adjust sessionID if user-scoped
    s.mu.Lock()
    defer s.mu.Unlock()
    // Find latest version and increment
    s.set(appName, userID, sessionID, fileName, nextVersion, artifact)
    return &SaveResponse{Version: nextVersion}, nil
}

Saving an Artifact in GCS Service

func (s *gcsService) Save(ctx context.Context, req *artifact.SaveRequest) (*artifact.SaveResponse, error) {
    // Validate request
    // Determine nextVersion by listing versions
    blobName := buildBlobName(appName, userID, sessionID, fileName, nextVersion)
    writer := s.bucket.object(blobName).newWriter(ctx)
    // Write InlineData or Text to GCS blob
    return &artifact.SaveResponse{Version: nextVersion}, nil
}

Artifact Management Class Diagram

classDiagram
class Service {
<<interface>>
+Save(ctx, SaveRequest) SaveResponse
+Load(ctx, LoadRequest) LoadResponse
+Delete(ctx, DeleteRequest)
+List(ctx, ListRequest) ListResponse
+Versions(ctx, VersionsRequest) VersionsResponse
}
class InMemoryService {
-mu sync.RWMutex
-artifacts omap.Map
+Save()
+Load()
+Delete()
+List()
+Versions()
}
class GCSService {
-bucketName string
-storageClient gcsClient
-bucket gcsBucket
+Save()
+Load()
+Delete()
+List()
+Versions()
}
Service <|.. InMemoryService
Service <|.. GCSService

Summary of Subcomponents

This module is foundational for managing the lifecycle of artifact data within the agent workflows, enabling complex scenarios where artifacts must be versioned, shared, or retrieved efficiently during AI-driven sessions. It integrates tightly with session management and agent tooling to provide a seamless developer and runtime experience.

For more details on usage within agents and tools, see the Artifact Interface Adapter and related tooling in the [Tooling System](None - Tooling System).