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)

1. 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.

1. Merge into test

• Upsert the shared test version set with your candidate configuration.

• Run your simulation unit test set on test. Fix regressions here.

1. Promote to preview

• Copy the test configuration into preview (another named version set).

• Run the full simulation suite on preview and conduct stakeholder UAT.

1. 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

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: Keep the last known good configuration for release handy (export JSON or maintain a dedicated release-previous set) to enable quick rollback.

• Observability: Compare simulation metrics between test, preview, and release to quantify impact before promotion.

API Touchpoints (Operational Behavior)

API References

Create a service

post

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

Bearer-Authorization & Bearer-Authorization-OrganizationAPI-Key-Authorization-Key & API-Key-Authorization-ID & API-Key-Authorization-UserID

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

or

nullOptional

Sec-WebSocket-Protocolstring[]OptionalDefault: []

Body

application/json

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.

or

nullOptional

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.

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

HTTPcURLJavaScriptPython

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

{
  "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_o4-mini-2025-04-16",
        "top_p": 1,
        "temperature": 1,
        "top_k": 1
      }
    }
  },
  "tags": {
    "ANY_ADDITIONAL_PROPERTY": "text"
  }
}

{
  "id": "text"
}

Upsert a service version set

put

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

Bearer-Authorization & Bearer-Authorization-OrganizationAPI-Key-Authorization-Key & API-Key-Authorization-ID & API-Key-Authorization-UserID

Path parameters

service_idstringRequired

Identifier of the service.

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

version_set_namestring · min: 1Required

Name of the version set to upsert.

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

or

nullOptional

Sec-WebSocket-Protocolstring[]OptionalDefault: []

Body

application/json

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.

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

HTTPcURLJavaScriptPython

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

{
  "version_set": {
    "agent_version_number": 1,
    "service_hierarchical_state_machine_version_number": 1,
    "llm_model_preferences": {
      "ANY_ADDITIONAL_PROPERTY": {
        "llm_name": "openai_o4-mini-2025-04-16",
        "top_p": 1,
        "temperature": 1,
        "top_k": 1
      }
    }
  }
}

No content

Delete a service version set

delete

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

Bearer-Authorization & Bearer-Authorization-OrganizationAPI-Key-Authorization-Key & API-Key-Authorization-ID & API-Key-Authorization-UserID

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

or

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

HTTPcURLJavaScriptPython

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.