Deploy a built agent image

Deploy a successfully built agent image to Kubernetes as a Helm release.

Takes a completed build (referenced by build_id, or by image_name + image_tag) together with the agent manifest and environment config, then starts an asynchronous Temporal workflow that provisions the agent as a Helm release. The call returns immediately with the deployment record in PENDING status — it does not wait for the release to become healthy; poll GET /v5/agentex/deployments/{deployment_id} for status and Kubernetes events and GET /v5/agentex/deployments/{deployment_id}/logs for progress. This is the deploy counterpart to POST /v5/agentex/builds: a build produces the container image, a deployment runs that image. The referenced build must have finished successfully, and the manifest’s agent name must match the build’s agent.

Set preview=True for an ephemeral deployment: it gets a globally unique Helm release name (so concurrent redeploys never collide), an optional preview_label for grouping, and an expiry (expires_at, defaulting to 8 hours from now); preview_label and expires_at are rejected on non-preview deploys. A non-preview (production) deploy instead supersedes any prior active deployment that shares its Helm release name. Fails with a client error if the build is missing or not in a successful state, if the manifest or environment YAML is invalid or their agent names disagree, or if a secret referenced by the manifest does not exist. Returns 409 if the target agent has an active key migration or an applicable incomplete managed-key handoff.

POST /v5/agentex/deployments

Deploy a built agent image

cURL

curl --request POST \
  --url https://api.egp.scale.com/v5/agentex/deployments \
  --header 'Content-Type: application/json' \
  --header 'x-api-key: <api-key>' \
  --data '
{
  "manifest_file": "<string>",
  "environment_config": "<string>",
  "build_id": "<string>",
  "image_name": "<string>",
  "image_tag": "<string>",
  "preview": false,
  "preview_label": "<string>",
  "expires_at": "2023-11-07T05:31:56Z"
}
'

200

{
  "id": "<string>",
  "namespace": "<string>",
  "manifest_file": "<string>",
  "environment_config": "<string>",
  "status": "<string>",
  "account_id": "<string>",
  "created_at": "2023-11-07T05:31:56Z",
  "created_by": {
    "id": "<string>",
    "type": "user",
    "object": "identity"
  },
  "object": "agentex_cloud_deploy",
  "build_id": "<string>",
  "image_digest": "<string>",
  "helm_release_name": "<string>",
  "expires_at": "2023-11-07T05:31:56Z",
  "preview_label": "<string>",
  "deploy_events": [
    {
      "type": "<string>",
      "reason": "<string>",
      "message": "<string>",
      "timestamp": "2023-11-07T05:31:56Z"
    }
  ]
}

Authorizations

x-api-key · string · header · required

Headers

x-selected-account-id · string | null

Body

application/json

manifest_file · string · required

YAML content of manifest configuration.

environment_config · string · required

YAML content of environment configuration from the environment config file.

build_id · string | null

The build_id of the cloud build. Required if image_name and image_tag are not provided.

image_name · string | null

Name of the image to deploy. Required if build_id is not provided.

image_tag · string | null

Tag of the image to deploy. Required if build_id is not provided.

preview · boolean | null · default: false

When True, creates a preview deployment with a unique deployment-id suffix appended to the helm release name.

preview_label · string | null

Non-unique grouping label for the preview (e.g. branch name, PR number). Persisted on the deployment record so callers can list all deploys for a given label via GET /v5/agentex/deployments?preview_label=X (add sort_order=desc&limit=1 for the latest). Sanitized to lowercase alphanumeric + hyphens for K8s DNS-label compatibility (max 30 characters after sanitization). Each deploy still gets a unique helm release name regardless of label, so concurrent redeploys never share K8s resources. Only valid when preview=True.

expires_at · string<date-time> | null

ISO 8601 expiry timestamp. Only valid for preview deployments. If omitted on a preview deployment, defaults to 8 hours from now. Previews are always ephemeral and always have an expires_at.

Response

200

application/json

Successful Response

id · string · required

The unique identifier of the deployment.

namespace · string · required

Kubernetes namespace where the deployment is deployed.

manifest_file · string · required

YAML content of manifest configuration.

environment_config · string · required

YAML content of environment configuration from the environment config file.

status · string · required

Deployment status: pending, running, completed, failed, or cancelled.

account_id · string · required

The ID of the account that owns the given entity.

created_at · string<date-time> · required

The date and time when the entity was created in ISO format.

created_by · Identity · object · required

The identity that created the entity.

Show child attributes

object · string · default: agentex_cloud_deploy

Allowed value: "agentex_cloud_deploy"

build_id · string | null

The build_id of the cloud build that produced the deployed image.

image_digest · string | null

Registry manifest digest of the deployed image, served from the linked build record. Null when the build recorded no digest.

helm_release_name · string | null

Helm release name after successful deployment.

expires_at · string<date-time> | null

When this deployment will be cleaned up. Always set on preview deployments (defaults to 8 hours from creation if the request omits it). Null on non-preview deployments — they have no TTL.

preview_label · string | null

Non-unique grouping label for preview deployments. Filter ?preview_label=X&sort_order=desc&limit=1 returns the latest deploy for the label. Sanitized (lowercase alphanumeric + hyphens) and capped at 30 characters.

deploy_events · AgentexCloudDeployEvent · object[]

Kubernetes events for this deployment.

Show child attributes