Workflow Reference Model#

The Reference model is agenta's unified way to address workflows (applications), variants, and environments in API calls. Instead of requiring a UUID everywhere, callers can identify a resource by slug alone, by slug + version, or by id — the server resolves whichever combination is provided.

Core Types#

Three Fern-generated SDK types represent references at different points in the request/response lifecycle:

ReferenceRequestModel and ReferenceDto are structurally identical (both frozen Pydantic models with extra="allow") 1 2. Reference differs in that version is a str rather than int and adds an attributes dict for arbitrary key-value metadata 3.

The server-side counterpart is ReferenceDTO in api/oss/src/services/variants_manager.py, which adds UUID serialization logic and an encode() helper for nested structures.

Three Reference Roles per API Call#

Every /variants/configs/* endpoint accepts up to three separate reference objects — one per entity type 4:

• application_ref — identifies the app/workflow (by id or slug)
• variant_ref — identifies the variant (by id, or slug + optional version)
• environment_ref — identifies the deployment environment (by id, or slug + optional version)

The ConfigResponseModel returned by these endpoints includes all three refs populated with resolved values, plus lifecycle metadata (committed_at, deployed_at, etc.) 5.

Resolution Logic#

The server uses a dual-strategy lookup 6:

1. By id — direct DB lookup, preferred for performance.
2. By slug + application_ref — resolves the app first (by id or slug), then resolves the variant/environment within that app. If version is omitted, the latest revision is returned.

Environment resolution differs slightly: version=None always means "latest" for environments, whereas variant resolution requires an explicit flag 7.

SDK Usage: _ref_or_none and SharedManager#

SharedManager._ref_or_none() is the SDK helper that constructs a ReferenceRequestModel from loose keyword arguments — returning None if all fields are absent. It is called at every SharedManager method boundary before dispatching to the API client 8.

For example, SharedManager.fetch() accepts variant_slug, variant_version, app_slug, etc. and assembles three reference objects before calling ag.api.variants.configs_fetch() 9. The same pattern applies to add, commit, fork, deploy, delete, and their async counterparts.

Validation rules enforced by _parse_fetch_request 10:

• variant_slug requires app_id or app_slug
• variant_version requires variant_slug
• environment_slug requires app_id or app_slug
• environment_version requires environment_slug

Relationship to Other Identifier Systems#

• Slugs are project-scoped, URL-safe strings ([a-zA-Z0-9_-]+) validated by the Slug DTO mixin 11. References carry slugs but do not validate them — validation happens at the slug layer.
• UUIDs (id) are globally unique per revision. Prefer id when performance matters; prefer slug for human-readable scripts and configuration.
• The Reference model is not the same as tool execution types (e.g., ToolCall, FunctionCall). It is purely an addressing/routing mechanism for workflow and variant resources.
• In run-context tracing (runContext), workflow.id, workflow.slug, and workflow.version correspond to the same slug/id/version fields but are embedded in the OTel span context rather than passed as Reference objects 12.

Key Source Files#