Version Sets & Promotion

Manage version sets for safe deployment promotion from development through production.

Version sets define which agent, state machine, and model preferences a service uses. They let you iterate safely, 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.

Every service carries two special sets, edge and release, with platform-enforced guardrails:

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 they're referenced by simulation unit tests.

What Each Special Set Means

edge (locked default settings)
- Always the latest agent and state machine, with no explicit LLM preferences.
- Cannot be updated via the upsert API and cannot be deleted.
- Use it 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 (for example, 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 equals edge unless you specify otherwise at creation time.

Recommended Workflow (Git-Branch Style)

Personal branch
- Create a personal version set (for example, personal-yourname) with forge version-set upsert personal-yourname -s MyService -e <env> --latest --apply, pin agent and state machine versions, and set LLM preferences.
- Iterate locally and validate via small, focused simulation unit tests.
Merge into test
- Upsert the shared test version set with your candidate configuration (--copy-from personal-yourname).
- Run your simulation unit test set on test. Fix regressions here.
Promote to preview
- Copy the test configuration into preview with forge version-set upsert preview -s MyService -e <env> --copy-from test --apply.
- Run the full simulation suite on preview and conduct stakeholder UAT.
Release
- If preview passes full sims and UAT, promote with forge version-set promote preview release -s MyService -e <env> --apply, which auto-creates a release-previous backup for one-command rollback.
- Don't delete release or edge. Use them as stable anchors.

Promotion Flow

CLI Reference

The Agent Forge CLI covers the full version-set lifecycle from the terminal: listing and inspecting sets, upserting with pinned or copied configurations, diffing, promoting with auto-backup, rolling back, and discovering services and asset versions. All mutating commands are dry-run by default and run pre-flight validation.

Version Set CLI Reference

Validation rules for channels, presets, and LLM preferences are driven by service tags. See Channel Tagging: Validation for the canonical rules table.

Practical Tips

Naming Conventions

Names may contain letters, digits, -, and _ only, with a maximum length of 40 characters.
Prefer lowercase for readability and consistency.
Examples: personal-alex, test, preview, release.

Operating Tips

Drift control: treat release as immutable except during deliberate promotion. Keep a changelog of which version set was promoted, when, and by whom.
Deprecate rather than delete: the platform blocks deletion of sets referenced by simulations. When many artifacts depend on a set, prefer deprecation and migration over deletion.
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

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

The username should be set to {org_id}_{user_id}, and the password should be the Amigo issued JWT token that identifies the user.

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-namestring · nullableOptional

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.

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.

keytermsstring[] · max: 20Required

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

Responses

201

Succeeded.

application/json

idstringRequired

The ID of the newly created service.

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: 424

{
  "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": "openai_gpt-5.2-2025-12-11",
        "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

The username should be set to {org_id}_{user_id}, and the password should be the Amigo issued JWT token that identifies the user.

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-namestring · nullableOptional

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.

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: 237

{
  "version_set": {
    "agent_version_number": 1,
    "service_hierarchical_state_machine_version_number": 1,
    "llm_model_preferences": {
      "ANY_ADDITIONAL_PROPERTY": {
        "llm_name": "openai_gpt-5.2-2025-12-11",
        "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

The username should be set to {org_id}_{user_id}, and the password should be the Amigo issued JWT token that identifies the user.

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-namestring · nullableOptional

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.

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

These endpoints enforce the guardrails described above: service creation initializes both special sets, the upsert API accepts release and custom sets, and the delete API rejects the protected and simulation-referenced sets.

PreviousMulti-Org Strategy (Region x Project)

NextVersion Set CLI Reference

Last updated 1 month ago

Was this helpful?