Playground Variant Architecture#

The Agenta playground is organized around variants and revisions rather than chat sessions. A variant is a named LLM configuration (model, prompt template, parameters) belonging to an application. Each time a variant's config is saved, a new revision is appended to its history — giving users a full audit trail and the ability to restore any prior configuration.

Core Data Model#

The backend stores this hierarchy in two PostgreSQL tables:

• AppVariantDB — the top-level variant record, holding variant_name, config_name, config_parameters (JSONB), and a revision integer that tracks the current head.
• AppVariantRevisionsDB — the append-only revision history. Each row captures a full snapshot of config_parameters, the revision number, an optional commit_message, and audit fields (modified_by_id, created_at, updated_at). The utility method get_config() returns {"config_name": ..., "parameters": ...} for consumers.

Variants and revisions also carry slug identifiers (URL-safe alphanumerics/underscores/hyphens) via the Slug mixin in the git-layer DTOs 1, and revisions additionally inherit the Commit mixin with author, date, and message fields 2.

The newer workflow layer uses parallel generic types — WorkflowVariant and WorkflowRevision — which extend the base Variant/Revision DTOs and field-alias artifact_id as workflow_id for domain clarity. WorkflowRevision.data carries a configuration dict (parameters, variables) and a service dict (URL, schema, kind) that fully describe the revision's runtime behavior 3.

Revision-Centric Frontend State#

A key architectural decision: the playground treats each revision as a first-class displayable unit, not each variant. When the playground loads, appSchemaMiddleware fetches the variant list, then fetches each variant's full revision history 4. The adaptRevisionToVariant() function in variant/utils.ts transforms each revision into an EnhancedVariant object, embedding the parent variant's identity in _parentVariant. The playground state's variants array therefore holds revision-level objects, not variant-level objects.

This means selecting "a variant" in the UI is actually selecting a specific revision of that variant. The isLatestRevision flag on EnhancedVariant is determined globally by comparing createdAtTimestamp values across all revisions of all variants 5.

Two-Phase Loading#

To minimize perceived latency, appSchemaMiddleware uses a two-phase strategy 6:

1. Priority load — extract revision IDs from the URL's revisions query parameter via getRevisionIdsFromUrl(), fetch only those revisions immediately to unblock rendering.
2. Background load — queue remaining revisions via queueMicrotask() 7 without blocking the UI thread.

The EnhancedVariant objects are cached in an out-of-React atomStore (allRevisionsAtom, variantsRefAtom) 8 so they can be accessed across middleware layers without prop-drilling.

usePlayground Middleware Stack#

All playground state flows through usePlayground, which composes six SWR middlewares in order:

The playground supports a comparison mode: when state.selected holds more than one variant ID, getViewType() returns "comparison" 9. URL state (?revisions=[...]) is kept in sync by PlaygroundWrapper 10.

Key API Endpoints#

Server-side orchestration lives in variants_manager.py, which handles fetch, fork, commit, deploy, and history operations.

Key Source Files#