Version Sets & Promotion

Version sets define which agent, state machine, and model preferences a service uses. They enable safe iteration like Git branches while keeping production stable.

Purpose: Pin exact versions for a service run (agent, state machine, LLM model preferences).
Analogy: Treat version sets like Git branches for your service configuration.
Two special sets exist on every service:
- edge: Always points to the latest agent and state machine with no model preferences. Locked from updates; cannot be deleted.
- release: The default version set used when clients don’t specify one. Cannot be deleted; can be updated to promote changes.

Guardrails

edge cannot be updated or deleted.
release cannot be deleted and is the default when no version set is specified.
Custom version sets cannot be deleted if referenced by simulation unit tests.

What Each Special Set Means

edge (locked default settings)
- Always latest agent/state machine; no explicit LLM preferences.
- Cannot be updated via the upsert API and cannot be deleted.
- Use for quick local validation or smoke checks; not for stable user exposure.
release (default exposed to users)
- Used by conversations and real-time APIs when service_version_set_name is not provided.
- Cannot be deleted, but can be updated to promote a tested configuration to production.

Creating and Updating Version Sets

Create/Update: Use the Service Version Set upsert API to create named sets (e.g., personal-alex, test, preview). All sets except edge are updatable.
Delete: Allowed for custom sets, but not for edge or release. Deletion is blocked if a set is referenced by any simulation unit tests.
Permissions:
- Create: Service:CreateVersionSet
- Update: Service:UpdateVersionSet
- Delete: Service:DeleteVersionSet

How Version Sets Are Used at Runtime

Conversation APIs default to release if service_version_set_name is omitted.
Simulation unit tests and test runs must explicitly specify the target version set.
Services are created with both edge and release by default; release will equal edge unless specified otherwise at creation time.

Real-time Voice (WebSocket)

Recommended Workflow (Git-Branch Style)

Personal branch

Create a personal version set (e.g., personal-yourname), pin agent/state machine versions and set LLM preferences.
Iterate locally; validate via small focused simulation unit tests.

Merge into test

Upsert the shared test version set with your candidate configuration.
Run your simulation unit test set on test. Fix regressions here.

Promote to preview

Copy the test configuration into preview (another named version set).
Run the full simulation suite on preview and conduct stakeholder UAT.

Release

If preview passes full sims and UAT, promote by updating release with the same configuration (i.e., upsert release to match preview).
Do not delete release or edge. Use them as stable anchors.

Promotion Flow

CLI Commands (`forge version-set`)

Agent Forge provides CLI commands to manage version sets directly from the terminal:

List Version Sets

forge version-set list MyService -e production

# JSON output for scripting
forge version-set list MyService -e production --json

Shows all version sets for a service with their pinned versions and LLM preferences.

Create/Update a Version Set

# Create with unpinned versions (dev only)
forge version-set upsert personal-alex -s MyService -e dogfood --apply

# Create with pinned versions (resolves current latest)
forge version-set upsert personal-alex -s MyService -e dogfood --latest --apply

# Create by copying from another version set
forge version-set upsert preview -s MyService -e production --copy-from test --apply

# Pin specific versions
forge version-set upsert preview -s MyService -e production -a 5 -g 3 --apply

Dry-run by default: All mutating commands show what would change without --apply. Add --apply to execute.

Version Existence Validation

When pinning to specific versions using -a (agent) or -g (context graph) flags, the CLI validates that those versions actually exist before applying the change:

$ forge version-set upsert preview -s MyService -e production -a 999 -g 888 --apply

Error: Agent version 999 does not exist. Use 'forge asset agent version-list' to see available versions.
Error: Context graph version 888 does not exist. Use 'forge asset context-graph version-list' to see available versions.

For advanced users who need to bypass this validation (e.g., in automation scripts where versions may be created in parallel), use the --skip-version-check flag:

forge version-set upsert preview -s MyService -e production -a 5 -g 3 --skip-version-check --apply

Use --skip-version-check with caution. Pinning non-existent versions will cause runtime failures when the service is invoked.

Compare Version Sets

forge version-set diff preview release -s MyService -e production

# JSON output for scripting
forge version-set diff preview release -s MyService -e production --json

Shows a side-by-side comparison of two version sets, highlighting differences.

Promote Version Sets

# Promote to release (auto-backup creates release-previous for easy rollback)
forge version-set promote preview release -s MyService -e production --apply

# Skip auto-backup if needed
forge version-set promote preview release -s MyService -e production --no-backup --apply

Auto-backup: When promoting to release, a backup is automatically created as release-previous. Use --no-backup to skip this safety measure.

Rollback Version Sets

If a release causes issues, quickly revert to the previous configuration:

# Preview what would be rolled back (dry-run)
forge version-set rollback -s MyService -e production

# Execute the rollback
forge version-set rollback -s MyService -e production --apply

This is equivalent to forge version-set promote release-previous release but provides a clearer intent and shows a comparison of the configurations:

Rollback 'release' to 'release-previous'
  Service: MyService (686d598b1234567890abcdef)
                         Configuration Comparison
┏━━━━━━━━━━━━━━━━━━━━━━━┳━━━━━━━━━━━━━━━━━━━━━━━━━━━━━┳━━━━━━━━━━━━━━━━━━━┓
┃ Field                 ┃ Previous (release-previous) ┃ Current (release) ┃
┡━━━━━━━━━━━━━━━━━━━━━━━╇━━━━━━━━━━━━━━━━━━━━━━━━━━━━━╇━━━━━━━━━━━━━━━━━━━┩
│ agent_version         │ 27                          │ 28                │
│ context_graph_version │ 3                           │ 4                 │
│ llm_preferences       │ 2 configured                │ 2 configured      │
└───────────────────────┴─────────────────────────────┴───────────────────┘

Dry-run mode. Use --apply to execute.

The release-previous version set is created automatically when promoting to release. If you've never promoted to release, or used --no-backup, the rollback command will fail with an error.

Show Version Set Details

# Human-readable format
forge version-set show preview -s MyService -e production

# JSON output (for scripting)
forge version-set show preview -s MyService -e production --json

Delete a Version Set

forge version-set delete test-old -s MyService -e dogfood --apply

Cannot delete edge or release. Cannot delete version sets referenced by simulation unit tests.

Discovering Services (`forge service`)

Before working with version sets, you may need to discover what services exist and their current configuration. Use forge service commands to list and inspect services.

List Services

# List all services in an environment
forge service list -e production

# Filter by tag (e.g., production, phone, voice)
forge service list -e production --tag phone

# JSON output for scripting
forge service list -e production --json

Output shows services with their tags and version set counts:

Services in production
Filtered by tag: phone

┏━━━━━━━━━━━━━━━━━━━━━━━━━━━┳━━━━━━━━━━━━━┳━━━━━━━━━━━━━━━━━━━━━┳━━━━━━━━━━━━━━┓
┃ Name                      ┃ ID          ┃ Tags                ┃ Version Sets ┃
┡━━━━━━━━━━━━━━━━━━━━━━━━━━━╇━━━━━━━━━━━━━╇━━━━━━━━━━━━━━━━━━━━━╇━━━━━━━━━━━━━━┩
│ Customer Support          │ 686d598b... │ phone, voice        │            3 │
│ Sales Assistant           │ 68bb4c7f... │ phone, production   │            2 │
└───────────────────────────┴─────────────┴─────────────────────┴──────────────┘

Show Service Details

# Show full service configuration
forge service show "Customer Support" -e production

# JSON output for scripting
forge service show "Customer Support" -e production --json

Output includes linked assets and version set configuration:

Service: Customer Support
  ID: 686d598b1234567890abcdef
  Description: Voice support agent
  Active: Yes

Tags:
  - phone
  - voice

Linked Assets:
  Agent: support_agent (66e0d996f5a09fb3cf18ea73)
  Context Graph: support_hsm (66e0d575f5a09fb3cf18ea5e)

Version Sets:
  Name       Agent Ver    CG Ver    LLM Config
  edge          latest    latest    defaults
  preview           28         4    2 set
  release           28         4    2 set

Related commands:
  forge version-set list Customer Support -e production
  forge asset agent version-list support_agent -e production

Check Service Health Status

Monitor the health of services across your organization to identify configuration issues:

# Check status of active services only (default behavior)
forge service status -e production

# Include inactive/disabled services in the analysis
forge service status -e production --include-inactive

# Focus on production-tagged services only
forge service status -e production --production

# Show only services with issues
forge service status -e production --issues

# Filter by tag
forge service status -e production --tag phone

# JSON output for monitoring/alerting
forge service status -e production --json

Detected Issues:

Version set drift: Preview and release configurations differ
Missing version sets: Production services missing preview or release
Unpinned versions: Production services with non-edge version sets using latest

Example Output:

Service Status in production

Summary:
  Total services: 8  # Only showing active services by default
  Production services: 3
  Services with issues: 2
    - With preview/release drift: 2

Services Needing Attention:

Name           ID          Active  Prod   Preview  Release  Issues
MyService      507f1f7...  Yes     Yes    Yes      Yes      preview/release drift
OtherService   508f2a8...  Yes     Yes    No       Yes      missing preview

Discovery workflow: Use forge service list to find services, forge service status to check health, then forge service show to inspect configuration before making changes with forge version-set commands.

Discovering Asset Versions (`forge asset`)

Before pinning specific versions in a version set, you need to know what versions exist. Use forge asset commands to discover agent and context graph versions.

List Agent Versions

# List versions for an agent by name
forge asset agent version-list MyAgent -e production

# List by agent ID
forge asset agent version-list 507f1f77bcf86cd799439011 -e production

Output shows version numbers with creation timestamps:

Versions for Agent: MyAgent (507f1f77bcf86cd799439011)

┏━━━━━━━━━┳━━━━━━━━━━━━━━━━━━┳━━━━━━━━━━━━━┓
┃ Version ┃ Created          ┃ Description ┃
┡━━━━━━━━━╇━━━━━━━━━━━━━━━━━━╇━━━━━━━━━━━━━┩
│       1 │ 2024-04-11 23:52 │ —           │
│       2 │ 2025-01-30 19:38 │ —           │
│       3 │ 2025-01-30 19:51 │ —           │
└─────────┴──────────────────┴─────────────┘

List Context Graph Versions

forge asset context-graph version-list MyGraph -e production

Output includes state count for each version:

Versions for Context Graph: MyGraph (66997b4d40fe08f84ba0d1d1)

┏━━━━━━━━━┳━━━━━━━━━━━━━━━━━━┳━━━━━━━━┳━━━━━━━━━━━━━━━━━━━━━━┓
┃ Version ┃ Created          ┃ States ┃ Description          ┃
┡━━━━━━━━━╇━━━━━━━━━━━━━━━━━━╇━━━━━━━━╇━━━━━━━━━━━━━━━━━━━━━━┩
│       1 │ 2024-07-18 20:45 │     21 │ Initial version      │
│       2 │ 2024-08-07 17:06 │     22 │ Added new state      │
│       3 │ 2025-02-10 20:14 │     22 │ Bug fixes            │
└─────────┴──────────────────┴────────┴──────────────────────┘

Show Version Details

# Agent version details
forge asset agent version-show MyAgent 3 -e production

# Context graph version details (shows state breakdown)
forge asset context-graph version-show MyGraph 2 -e production

# JSON output for scripting
forge asset agent version-show MyAgent 3 -e production --json

Workflow: Pin Discovered Versions

# 1. Discover latest agent version
forge asset agent version-list MyAgent -e production

# 2. Discover latest context graph version
forge asset context-graph version-list MyGraph -e production

# 3. Pin specific versions in a version set
forge version-set upsert preview -s MyService -e production -a 3 -g 2 --apply

Tip: Use forge version-set upsert --latest to automatically resolve and pin the current latest versions without manually looking them up.

CLI Validation

All mutating version-set commands (upsert, promote, delete) run pre-flight validation before applying changes. This ensures configurations are valid before reaching the remote API.

Validation Rules

Rule

Scope

Behavior

Version existence check

All upsert commands

Error if pinned agent/HSM version doesn't exist

Pinned versions required

Production services

Error if agent/HSM version is null

Cannot delete preview/release

Production services

Error blocks deletion

Preview required for release promotion

Production services

Error if preview doesn't exist

Voice-optimized LLMs only

Voice channels

Error if using GPT-5, Claude, etc.

Empty LLM prefs warning

Voice channels

Warning (non-blocking)

Cost tier constraints

Economy presets

Error if using premium LLMs

Bypass validation: Use --skip-version-check to bypass version existence validation for advanced use cases.

Example: Blocked Mutation

$ forge version-set upsert preview -s "Voice Service" -e production --apply

Error: Version set 'preview' uses non-voice-optimized LLM 'azure_gpt-5-2025-08-07'.
Voice preset 'voice' requires voice-optimized LLMs. Valid: ['azure_gpt-4.1-2025-04-14',
'azure_gpt-4.1-mini-2025-04-14']

Validation failed. Fix errors before proceeding.

Example: Warning (Non-blocking)

Warnings are displayed but don't block the operation:

$ forge version-set upsert test -s "Voice Service" -e dogfood --apply

Warning: Version set 'test' has empty llm_model_preferences. System defaults may
include non-voice-optimized LLMs. For voice preset 'voice', configure LLM preferences
explicitly using voice-optimized LLMs.

Create version set 'test'
  Service: Voice Service (66e0da39f5a09fb3cf18ea75)
  Agent version: latest
  Context Graph version: latest

Dry-run mode. Use --apply to execute.

Channel and preset tags determine which validation rules apply. See Channel Tagging for details on configuring service tags.

Practical Tips

Naming Conventions

Use lowercase letters, digits, - or _ only.
Don’t use /, ., or names starting with $.
Examples: personal-alex, test, preview, release.
Drift control: Treat release as immutable except during deliberate promotion. Keep a changelog of which version set was promoted, when, and by whom.
Safety checks: Block deletion of sets referenced by simulations. Prefer deprecation and migration over deletion when many artifacts depend on a set.
Fast rollback: Use forge version-set rollback to quickly revert to the previous release configuration. The release-previous backup is created automatically when promoting to release.
Observability: Compare simulation metrics between test, preview, and release to quantify impact before promotion.

API Touchpoints (Operational Behavior)

API References

Create a service

post

/v1/{organization}/service/

Create a new service. Depending on whether an active service with the same name already exists, the endpoint behaves differently:

If is_active is False, creates an inactive new service.
If is_active is True and no active service with the given name exists, creates a new active service.
If is_active is True and an active service with the given name exists, this endpoint throws an error.

The new service will automatically contain an edge version set that uses the latest Agent and ServiceHierarchicalStateMachine versions with no LLM model preference. It will also create a release version set, that will equal to what's specified in the request if the release_version_set is specified, or equal to edge if not.

Permissions

This endpoint requires the following permissions:

Service:CreateService for the service to create.
Service:CreateVersionSet for the edge and release version sets.

Authorizations

AuthorizationstringRequired

Amigo issued JWT token that identifies an user. It's issued either after logging in through the frontend, or manually through the SignInWithAPIKey endpoint.

X-ORG-IDstringRequired

An optional organization identifier that indicates from which organization the token is issued. This is used in rare cases where the user to authenticate is making a request for resources in another organization.

Path parameters

organizationstringRequired

Header parameters

x-mongo-cluster-nameany ofOptional

The Mongo cluster name to perform this request in. This is usually not needed unless the organization does not exist yet in the Amigo organization infra config database.

stringOptional

nullOptional

Sec-WebSocket-Protocolstring[]OptionalDefault: []

Body

service_hierarchical_state_machine_idstringRequired

The ID of the state machine that this service uses.

Pattern: ^[a-f0-9]{24}$

agent_idstringRequired

The ID of the agent that this service uses.

Pattern: ^[a-f0-9]{24}$

namestring · min: 1Required

The name of this service.

descriptionstring · min: 1Required

A description of this service.

is_activebooleanRequired

Whether the newly-created service is active. Only active services are visible to users on the dashboard. You can later adjust the activeness of this service.

release_version_setany ofOptional

The release version set to use for this service. If not specified, the release version set will be the same as the edge version set, which uses the latest agent and state machine versions with no model preference.

nullOptional

keytermsstring[] · max: 20Optional

A list of keyterms that are easy to get wrong during audio transcriptions that tend to occur commonly in audio sessions using this service.

Default: []

Responses

201

Succeeded.

application/json

400

This error could be thrown due to the following reasons:

The specified ID for agent or service hierarchical state machine versions in the release version set does not belong to the agent or service hierarchical state machine of the service.
The specified agent or state machine doesn't have any versions.
The specified LLM config is invalid.

401

Invalid authorization credentials.

403

Missing required permissions.

404

The specified organization, agent, or service hierarchical state machine do not exist.

409

An active service with the given name already exists.

422

Invalid request path parameter or request body failed validation.

429

The user has exceeded the rate limit of 20 requests per minute for this endpoint.

503

The service is going through temporary maintenance.

post

/v1/{organization}/service/

POST /v1/{organization}/service/ HTTP/1.1
Host: api.amigo.ai
Authorization: Bearer YOUR_SECRET_TOKEN
X-ORG-ID: YOUR_API_KEY
Content-Type: application/json
Accept: */*
Content-Length: 423

{
  "service_hierarchical_state_machine_id": "text",
  "agent_id": "text",
  "name": "text",
  "description": "text",
  "is_active": true,
  "release_version_set": {
    "agent_version_number": 1,
    "service_hierarchical_state_machine_version_number": 1,
    "llm_model_preferences": {
      "ANY_ADDITIONAL_PROPERTY": {
        "llm_name": "azure_gpt-4.1-2025-04-14",
        "params": {
          "ANY_ADDITIONAL_PROPERTY": "anything"
        }
      }
    }
  },
  "keyterms": [
    "text"
  ],
  "tags": {
    "ANY_ADDITIONAL_PROPERTY": "text"
  }
}

{
  "id": "text"
}

Upsert a service version set

put

/v1/{organization}/service/{service_id}/version_sets/{version_set_name}/

Upsert a version set for the specified service. Replace the existing version set with the same name if any, or create a new one.

Note that the edge version set cannot be updated.

Permissions

This endpoint may require the following permissions:

Service:CreateVersionSet if the version set does not exist.
Service:UpdateVersionSet if the version set already exists.

Authorizations

AuthorizationstringRequired

Amigo issued JWT token that identifies an user. It's issued either after logging in through the frontend, or manually through the SignInWithAPIKey endpoint.

X-ORG-IDstringRequired

Path parameters

service_idstringRequired

Identifier of the service.

Pattern: ^[a-f0-9]{24}$

version_set_namestring · min: 1 · max: 40Required

Name of the version set to upsert.

Pattern: ^[A-Za-z0-9_-]+$

organizationstringRequired

Header parameters

x-mongo-cluster-nameany ofOptional

The Mongo cluster name to perform this request in. This is usually not needed unless the organization does not exist yet in the Amigo organization infra config database.

stringOptional

nullOptional

Sec-WebSocket-Protocolstring[]OptionalDefault: []

Body

Responses

204

Succeeded.

No content

400

The agent or service hierarchical state machine version in the request do not belong to the agent or state machine of the service, or attempted to update the edge version set, or the supplied LLM config is invalid.

401

Invalid authorization credentials.

403

Missing required permissions.

404

The specified organization or service do not exist.

422

Invalid request path parameter or request body failed validation.

429

The user has exceeded the rate limit of 30 requests per minute for this endpoint.

503

The service is going through temporary maintenance.

put

/v1/{organization}/service/{service_id}/version_sets/{version_set_name}/

PUT /v1/{organization}/service/{service_id}/version_sets/{version_set_name}/ HTTP/1.1
Host: api.amigo.ai
Authorization: Bearer YOUR_SECRET_TOKEN
X-ORG-ID: YOUR_API_KEY
Content-Type: application/json
Accept: */*
Content-Length: 236

{
  "version_set": {
    "agent_version_number": 1,
    "service_hierarchical_state_machine_version_number": 1,
    "llm_model_preferences": {
      "ANY_ADDITIONAL_PROPERTY": {
        "llm_name": "azure_gpt-4.1-2025-04-14",
        "params": {
          "ANY_ADDITIONAL_PROPERTY": "anything"
        }
      }
    }
  }
}

No content

Delete a service version set

delete

/v1/{organization}/service/{service_id}/version_sets/{version_set_name}/

Delete the given verion set from the given service.

This endpoint will error if the version set is used in any simulation unit tests.

Permissions

This endpoint requires the following permissions:

Service:DeleteVersionSet for the version set.

Authorizations

AuthorizationstringRequired

Amigo issued JWT token that identifies an user. It's issued either after logging in through the frontend, or manually through the SignInWithAPIKey endpoint.

X-ORG-IDstringRequired

Path parameters

organizationstringRequired

service_idstringRequired

Identifier of the service.

Pattern: ^[a-f0-9]{24}$

version_set_namestringRequired

Name of the version set.

Header parameters

x-mongo-cluster-nameany ofOptional

The Mongo cluster name to perform this request in. This is usually not needed unless the organization does not exist yet in the Amigo organization infra config database.

stringOptional

nullOptional

Sec-WebSocket-Protocolstring[]OptionalDefault: []

Responses

204

Succeeded.

No content

400

The specified version set is used in a simulation unit test, or is the edge or release version set.

401

Invalid authorization credentials.

403

Missing required permissions.

404

The specified organization, service, or version set do not exist.

422

Invalid request path parameter failed validation.

429

The user has exceeded the rate limit of 30 requests per minute for this endpoint.

503

The service is going through temporary maintenance.

delete

/v1/{organization}/service/{service_id}/version_sets/{version_set_name}/

DELETE /v1/{organization}/service/{service_id}/version_sets/{version_set_name}/ HTTP/1.1
Host: api.amigo.ai
Authorization: Bearer YOUR_SECRET_TOKEN
X-ORG-ID: YOUR_API_KEY
Accept: */*

No content

- Service creation initializes `edge` and `release`. - Upsert version set API cannot update `edge` but can update `release` and custom sets. - Delete version set API forbids deleting `edge` and `release`, and blocks deletion if a set is used in simulation unit tests. - Conversation and real-time endpoints default to `release` when a version set isn’t specified by the client.

This model lets teams branch, test, and promote changes in a controlled path: personal → test → preview → release, ensuring production remains stable while iteration stays fast.

PreviousMulti‑Org Strategy (Region × Project)NextChannel Tagging System

Last updated 5 days ago

Was this helpful?

Good night

hashtagWhat Each Special Set Means

hashtagCreating and Updating Version Sets

hashtagHow Version Sets Are Used at Runtime

hashtagRecommended Workflow (Git-Branch Style)

hashtagPromotion Flow

hashtagCLI Commands (forge version-set)

hashtagList Version Sets

hashtagCreate/Update a Version Set

hashtagVersion Existence Validation

hashtagCompare Version Sets

hashtagPromote Version Sets

hashtagRollback Version Sets

hashtagShow Version Set Details

hashtagDelete a Version Set

hashtagDiscovering Services (forge service)

hashtagList Services

hashtagShow Service Details

hashtagCheck Service Health Status

hashtagDiscovering Asset Versions (forge asset)

hashtagList Agent Versions

hashtagList Context Graph Versions

hashtagShow Version Details

hashtagWorkflow: Pin Discovered Versions

hashtagCLI Validation

hashtagValidation Rules

hashtagExample: Blocked Mutation

hashtagExample: Warning (Non-blocking)

hashtagPractical Tips

hashtagNaming Conventions

hashtagAPI Touchpoints (Operational Behavior)

hashtagAPI References

hashtagCreate a service

Permissions

hashtagUpsert a service version set

Permissions

hashtagDelete a service version set

Permissions

What Each Special Set Means

Creating and Updating Version Sets

How Version Sets Are Used at Runtime

Recommended Workflow (Git-Branch Style)

Promotion Flow

CLI Commands (`forge version-set`)

List Version Sets

Create/Update a Version Set

Version Existence Validation

Compare Version Sets

Promote Version Sets

Rollback Version Sets

Show Version Set Details

Delete a Version Set

Discovering Services (`forge service`)

List Services

Show Service Details

Check Service Health Status

Discovering Asset Versions (`forge asset`)

List Agent Versions

List Context Graph Versions

Show Version Details

Workflow: Pin Discovered Versions

CLI Validation

Validation Rules

Example: Blocked Mutation

Example: Warning (Non-blocking)

Practical Tips

Naming Conventions

API Touchpoints (Operational Behavior)

API References

Create a service

Upsert a service version set

Delete a service version set