# Deploy ## Deploy a built agent image `client.Deploy.New(ctx, body) (*AgentexCloudDeploy, error)` **post** `/v5/agentex/deployments` 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. ### Parameters - `body DeployNewParams` - `EnvironmentConfig param.Field[string]` YAML content of environment configuration from the environment config file. - `ManifestFile param.Field[string]` YAML content of manifest configuration. - `BuildID param.Field[string]` The build_id of the cloud build. Required if image_name and image_tag are not provided. - `ExpiresAt param.Field[Time]` 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. - `ImageName param.Field[string]` Name of the image to deploy. Required if build_id is not provided. - `ImageTag param.Field[string]` Tag of the image to deploy. Required if build_id is not provided. - `Preview param.Field[bool]` When True, creates a preview deployment with a unique deployment-id suffix appended to the helm release name. - `PreviewLabel param.Field[string]` 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&limit=1` (get 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. ### Returns - `type AgentexCloudDeploy struct{…}` - `ID string` The unique identifier of the deployment. - `AccountID string` The ID of the account that owns the given entity. - `CreatedAt Time` The date and time when the entity was created in ISO format. - `CreatedBy Identity` The identity that created the entity. - `ID string` - `Type IdentityType` - `const IdentityTypeUser IdentityType = "user"` - `const IdentityTypeServiceAccount IdentityType = "service_account"` - `Object IdentityObject` - `const IdentityObjectIdentity IdentityObject = "identity"` - `EnvironmentConfig string` YAML content of environment configuration from the environment config file. - `ManifestFile string` YAML content of manifest configuration. - `Namespace string` Kubernetes namespace where the deployment is deployed. - `Status string` Deployment status: pending, running, completed, failed, or cancelled. - `BuildID string` The build_id of the cloud build that produced the deployed image. - `DeployEvents []AgentexCloudDeployEvent` Kubernetes events for this deployment. - `Message string` Full event message. - `Reason string` Short reason, e.g. 'Pulling', 'Scheduled'. - `Timestamp Time` When the event was observed. - `Type string` Event type, e.g. 'Normal' or 'Warning'. - `ExpiresAt Time` 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. - `HelmReleaseName string` Helm release name after successful deployment. - `Object AgentexCloudDeployObject` - `const AgentexCloudDeployObjectAgentexCloudDeploy AgentexCloudDeployObject = "agentex_cloud_deploy"` - `PreviewLabel string` Non-unique grouping label for preview deployments. Filter `?preview_label=X&limit=1` returns the latest deploy for the label. Sanitized (lowercase alphanumeric + hyphens) and capped at 30 characters. ### Example ```go package main import ( "context" "fmt" "github.com/scaleapi/sgp-dev-go" "github.com/scaleapi/sgp-dev-go/option" ) func main() { client := sgpdev.NewClient( option.WithAPIKey("My API Key"), option.WithAccountID("My Account ID"), ) agentexCloudDeploy, err := client.Deploy.New(context.TODO(), sgpdev.DeployNewParams{ EnvironmentConfig: "environment_config", ManifestFile: "manifest_file", }) if err != nil { panic(err.Error()) } fmt.Printf("%+v\n", agentexCloudDeploy.ID) } ``` #### Response ```json { "id": "id", "account_id": "account_id", "created_at": "2019-12-27T18:11:19.117Z", "created_by": { "id": "id", "type": "user", "object": "identity" }, "environment_config": "environment_config", "manifest_file": "manifest_file", "namespace": "namespace", "status": "status", "build_id": "build_id", "deploy_events": [ { "message": "message", "reason": "reason", "timestamp": "2019-12-27T18:11:19.117Z", "type": "type" } ], "expires_at": "2019-12-27T18:11:19.117Z", "helm_release_name": "helm_release_name", "object": "agentex_cloud_deploy", "preview_label": "preview_label" } ``` ## Get an agent deployment `client.Deploy.Get(ctx, deploymentID) (*AgentexCloudDeploy, error)` **get** `/v5/agentex/deployments/{deployment_id}` Get a single agent deployment by ID, including its current status and Kubernetes events. Returns the deployment record with its latest status and the associated Kubernetes events (`deploy_events`) observed for the release, which are useful for diagnosing why a deployment is still pending or unhealthy. Poll this after `POST /v5/agentex/deployments` to track the asynchronous deploy to completion. For the incremental log output rather than status and events, use `GET /v5/agentex/deployments/{deployment_id}/logs`. Returns 404 if no deployment with this ID exists for the caller's account. ### Parameters - `deploymentID string` ### Returns - `type AgentexCloudDeploy struct{…}` - `ID string` The unique identifier of the deployment. - `AccountID string` The ID of the account that owns the given entity. - `CreatedAt Time` The date and time when the entity was created in ISO format. - `CreatedBy Identity` The identity that created the entity. - `ID string` - `Type IdentityType` - `const IdentityTypeUser IdentityType = "user"` - `const IdentityTypeServiceAccount IdentityType = "service_account"` - `Object IdentityObject` - `const IdentityObjectIdentity IdentityObject = "identity"` - `EnvironmentConfig string` YAML content of environment configuration from the environment config file. - `ManifestFile string` YAML content of manifest configuration. - `Namespace string` Kubernetes namespace where the deployment is deployed. - `Status string` Deployment status: pending, running, completed, failed, or cancelled. - `BuildID string` The build_id of the cloud build that produced the deployed image. - `DeployEvents []AgentexCloudDeployEvent` Kubernetes events for this deployment. - `Message string` Full event message. - `Reason string` Short reason, e.g. 'Pulling', 'Scheduled'. - `Timestamp Time` When the event was observed. - `Type string` Event type, e.g. 'Normal' or 'Warning'. - `ExpiresAt Time` 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. - `HelmReleaseName string` Helm release name after successful deployment. - `Object AgentexCloudDeployObject` - `const AgentexCloudDeployObjectAgentexCloudDeploy AgentexCloudDeployObject = "agentex_cloud_deploy"` - `PreviewLabel string` Non-unique grouping label for preview deployments. Filter `?preview_label=X&limit=1` returns the latest deploy for the label. Sanitized (lowercase alphanumeric + hyphens) and capped at 30 characters. ### Example ```go package main import ( "context" "fmt" "github.com/scaleapi/sgp-dev-go" "github.com/scaleapi/sgp-dev-go/option" ) func main() { client := sgpdev.NewClient( option.WithAPIKey("My API Key"), option.WithAccountID("My Account ID"), ) agentexCloudDeploy, err := client.Deploy.Get(context.TODO(), "deployment_id") if err != nil { panic(err.Error()) } fmt.Printf("%+v\n", agentexCloudDeploy.ID) } ``` #### Response ```json { "id": "id", "account_id": "account_id", "created_at": "2019-12-27T18:11:19.117Z", "created_by": { "id": "id", "type": "user", "object": "identity" }, "environment_config": "environment_config", "manifest_file": "manifest_file", "namespace": "namespace", "status": "status", "build_id": "build_id", "deploy_events": [ { "message": "message", "reason": "reason", "timestamp": "2019-12-27T18:11:19.117Z", "type": "type" } ], "expires_at": "2019-12-27T18:11:19.117Z", "helm_release_name": "helm_release_name", "object": "agentex_cloud_deploy", "preview_label": "preview_label" } ``` ## List agent deployments `client.Deploy.List(ctx, query) (*CursorPage[AgentexCloudDeploy], error)` **get** `/v5/agentex/deployments` List the account's agent deployments, with pagination and optional filters. Returns the deployments the caller is authorized to read. Optionally filter by `build_id`, by `agent_name` (matched through each deployment's associated build), or by `preview_label`. A `preview_label` is non-unique — many deployments can share one (for example every deploy for a branch) — so combine it with `limit=1` to fetch the latest deployment for that label. This lists deployments (the running or attempted agent instances); to list the image builds they run, use the agentex builds API. ### Parameters - `query DeployListParams` - `AgentName param.Field[string]` Filter deployments by agent name (via associated build) - `BuildID param.Field[string]` Filter deployments by build ID - `EndingBefore param.Field[string]` - `Limit param.Field[int64]` - `PreviewLabel param.Field[string]` Filter deployments by preview label (e.g. branch name). The label is non-unique — many deployments can share it. Combine with limit=1 to get the latest deploy for that label. - `SortBy param.Field[string]` - `SortOrder param.Field[SortOrder]` - `StartingAfter param.Field[string]` ### Returns - `type AgentexCloudDeploy struct{…}` - `ID string` The unique identifier of the deployment. - `AccountID string` The ID of the account that owns the given entity. - `CreatedAt Time` The date and time when the entity was created in ISO format. - `CreatedBy Identity` The identity that created the entity. - `ID string` - `Type IdentityType` - `const IdentityTypeUser IdentityType = "user"` - `const IdentityTypeServiceAccount IdentityType = "service_account"` - `Object IdentityObject` - `const IdentityObjectIdentity IdentityObject = "identity"` - `EnvironmentConfig string` YAML content of environment configuration from the environment config file. - `ManifestFile string` YAML content of manifest configuration. - `Namespace string` Kubernetes namespace where the deployment is deployed. - `Status string` Deployment status: pending, running, completed, failed, or cancelled. - `BuildID string` The build_id of the cloud build that produced the deployed image. - `DeployEvents []AgentexCloudDeployEvent` Kubernetes events for this deployment. - `Message string` Full event message. - `Reason string` Short reason, e.g. 'Pulling', 'Scheduled'. - `Timestamp Time` When the event was observed. - `Type string` Event type, e.g. 'Normal' or 'Warning'. - `ExpiresAt Time` 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. - `HelmReleaseName string` Helm release name after successful deployment. - `Object AgentexCloudDeployObject` - `const AgentexCloudDeployObjectAgentexCloudDeploy AgentexCloudDeployObject = "agentex_cloud_deploy"` - `PreviewLabel string` Non-unique grouping label for preview deployments. Filter `?preview_label=X&limit=1` returns the latest deploy for the label. Sanitized (lowercase alphanumeric + hyphens) and capped at 30 characters. ### Example ```go package main import ( "context" "fmt" "github.com/scaleapi/sgp-dev-go" "github.com/scaleapi/sgp-dev-go/option" ) func main() { client := sgpdev.NewClient( option.WithAPIKey("My API Key"), option.WithAccountID("My Account ID"), ) page, err := client.Deploy.List(context.TODO(), sgpdev.DeployListParams{ }) if err != nil { panic(err.Error()) } fmt.Printf("%+v\n", page) } ``` #### Response ```json { "has_more": true, "items": [ { "id": "id", "account_id": "account_id", "created_at": "2019-12-27T18:11:19.117Z", "created_by": { "id": "id", "type": "user", "object": "identity" }, "environment_config": "environment_config", "manifest_file": "manifest_file", "namespace": "namespace", "status": "status", "build_id": "build_id", "deploy_events": [ { "message": "message", "reason": "reason", "timestamp": "2019-12-27T18:11:19.117Z", "type": "type" } ], "expires_at": "2019-12-27T18:11:19.117Z", "helm_release_name": "helm_release_name", "object": "agentex_cloud_deploy", "preview_label": "preview_label" } ], "total": 0, "limit": 0, "object": "list" } ``` ## Get agent deployment logs `client.Deploy.Logs(ctx, deploymentID, query) (*DeployLogsResponse, error)` **get** `/v5/agentex/deployments/{deployment_id}/logs` Get structured deployment log lines, with cursor-based pagination. Returns the deployment's log lines in time order together with a `next_cursor` and a `has_more` flag. Poll to stream logs incrementally: make the first call without a cursor, then pass the previous response's `next_cursor` as `cursor` on each subsequent call, stopping once the deployment reaches a terminal status. Unlike `GET /v5/agentex/deployments/{deployment_id}`, which returns the deployment's status and Kubernetes events, this returns the raw log output from the deploy process. Returns 404 if no deployment with this ID exists for the caller's account. ### Parameters - `deploymentID string` - `query DeployLogsParams` - `Cursor param.Field[string]` Cursor from previous response's next_cursor field - `Limit param.Field[int64]` Maximum number of log lines to return ### Returns - `type DeployLogsResponse struct{…}` Response containing structured deployment log lines with cursor-based pagination. The CLI can poll this endpoint to stream logs incrementally: 1. First call: no after_id 1. Subsequent calls: after_id=next_cursor from previous response 1. Stop polling when has_more is False and the deployment reaches a terminal status - `DeploymentID string` The deployment ID - `HasMore bool` True if there may be more lines beyond this page (len(lines) == limit). - `Lines []DeployLogsResponseLine` Structured log lines - `ID string` Unique log line identifier (time-ordered) - `Message string` Log line content after the K8s timestamp - `LogLevel string` Parsed log level (INFO, ERROR, WARN, DEBUG, FATAL) - `Timestamp Time` Parsed K8s log timestamp - `NextCursor string` Cursor for the next page. Pass this as the after_id query parameter to get subsequent logs. ### Example ```go package main import ( "context" "fmt" "github.com/scaleapi/sgp-dev-go" "github.com/scaleapi/sgp-dev-go/option" ) func main() { client := sgpdev.NewClient( option.WithAPIKey("My API Key"), option.WithAccountID("My Account ID"), ) response, err := client.Deploy.Logs( context.TODO(), "deployment_id", sgpdev.DeployLogsParams{ }, ) if err != nil { panic(err.Error()) } fmt.Printf("%+v\n", response.DeploymentID) } ``` #### Response ```json { "deployment_id": "deployment_id", "has_more": true, "lines": [ { "id": "id", "message": "message", "log_level": "log_level", "timestamp": "2019-12-27T18:11:19.117Z" } ], "next_cursor": "next_cursor" } ``` ## Delete and tear down a deployment `client.Deploy.Delete(ctx, deploymentID) (*AgentexCloudDeploy, error)` **delete** `/v5/agentex/deployments/{deployment_id}` Delete an agent deployment and tear down its Kubernetes resources. Deletes the deployment's Kubernetes resources first, then marks the record as `DELETED`; the underlying Helm release is subsequently uninstalled asynchronously by FluxCD once the resource is removed. If the Kubernetes teardown fails, the record is left unchanged and the call errors, so the delete can be safely retried. Rejects the call with a client error if the deployment is already in a terminal state (`DELETED`, `CANCELLED`, or `SUPERSEDED`) — a `SUPERSEDED` record shares its Helm release with the deployment that replaced it, so deleting it would tear down the live release. Returns 404 if no deployment with this ID exists for the caller's account. This removes a running deployment, not the image build behind it, which is managed separately through the agentex builds API. ### Parameters - `deploymentID string` ### Returns - `type AgentexCloudDeploy struct{…}` - `ID string` The unique identifier of the deployment. - `AccountID string` The ID of the account that owns the given entity. - `CreatedAt Time` The date and time when the entity was created in ISO format. - `CreatedBy Identity` The identity that created the entity. - `ID string` - `Type IdentityType` - `const IdentityTypeUser IdentityType = "user"` - `const IdentityTypeServiceAccount IdentityType = "service_account"` - `Object IdentityObject` - `const IdentityObjectIdentity IdentityObject = "identity"` - `EnvironmentConfig string` YAML content of environment configuration from the environment config file. - `ManifestFile string` YAML content of manifest configuration. - `Namespace string` Kubernetes namespace where the deployment is deployed. - `Status string` Deployment status: pending, running, completed, failed, or cancelled. - `BuildID string` The build_id of the cloud build that produced the deployed image. - `DeployEvents []AgentexCloudDeployEvent` Kubernetes events for this deployment. - `Message string` Full event message. - `Reason string` Short reason, e.g. 'Pulling', 'Scheduled'. - `Timestamp Time` When the event was observed. - `Type string` Event type, e.g. 'Normal' or 'Warning'. - `ExpiresAt Time` 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. - `HelmReleaseName string` Helm release name after successful deployment. - `Object AgentexCloudDeployObject` - `const AgentexCloudDeployObjectAgentexCloudDeploy AgentexCloudDeployObject = "agentex_cloud_deploy"` - `PreviewLabel string` Non-unique grouping label for preview deployments. Filter `?preview_label=X&limit=1` returns the latest deploy for the label. Sanitized (lowercase alphanumeric + hyphens) and capped at 30 characters. ### Example ```go package main import ( "context" "fmt" "github.com/scaleapi/sgp-dev-go" "github.com/scaleapi/sgp-dev-go/option" ) func main() { client := sgpdev.NewClient( option.WithAPIKey("My API Key"), option.WithAccountID("My Account ID"), ) agentexCloudDeploy, err := client.Deploy.Delete(context.TODO(), "deployment_id") if err != nil { panic(err.Error()) } fmt.Printf("%+v\n", agentexCloudDeploy.ID) } ``` #### Response ```json { "id": "id", "account_id": "account_id", "created_at": "2019-12-27T18:11:19.117Z", "created_by": { "id": "id", "type": "user", "object": "identity" }, "environment_config": "environment_config", "manifest_file": "manifest_file", "namespace": "namespace", "status": "status", "build_id": "build_id", "deploy_events": [ { "message": "message", "reason": "reason", "timestamp": "2019-12-27T18:11:19.117Z", "type": "type" } ], "expires_at": "2019-12-27T18:11:19.117Z", "helm_release_name": "helm_release_name", "object": "agentex_cloud_deploy", "preview_label": "preview_label" } ``` ## Domain Types ### Agentex Cloud Deploy - `type AgentexCloudDeploy struct{…}` - `ID string` The unique identifier of the deployment. - `AccountID string` The ID of the account that owns the given entity. - `CreatedAt Time` The date and time when the entity was created in ISO format. - `CreatedBy Identity` The identity that created the entity. - `ID string` - `Type IdentityType` - `const IdentityTypeUser IdentityType = "user"` - `const IdentityTypeServiceAccount IdentityType = "service_account"` - `Object IdentityObject` - `const IdentityObjectIdentity IdentityObject = "identity"` - `EnvironmentConfig string` YAML content of environment configuration from the environment config file. - `ManifestFile string` YAML content of manifest configuration. - `Namespace string` Kubernetes namespace where the deployment is deployed. - `Status string` Deployment status: pending, running, completed, failed, or cancelled. - `BuildID string` The build_id of the cloud build that produced the deployed image. - `DeployEvents []AgentexCloudDeployEvent` Kubernetes events for this deployment. - `Message string` Full event message. - `Reason string` Short reason, e.g. 'Pulling', 'Scheduled'. - `Timestamp Time` When the event was observed. - `Type string` Event type, e.g. 'Normal' or 'Warning'. - `ExpiresAt Time` 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. - `HelmReleaseName string` Helm release name after successful deployment. - `Object AgentexCloudDeployObject` - `const AgentexCloudDeployObjectAgentexCloudDeploy AgentexCloudDeployObject = "agentex_cloud_deploy"` - `PreviewLabel string` Non-unique grouping label for preview deployments. Filter `?preview_label=X&limit=1` returns the latest deploy for the label. Sanitized (lowercase alphanumeric + hyphens) and capped at 30 characters. ### Agentex Cloud Deploy Event - `type AgentexCloudDeployEvent struct{…}` Slim event representation for the API response. - `Message string` Full event message. - `Reason string` Short reason, e.g. 'Pulling', 'Scheduled'. - `Timestamp Time` When the event was observed. - `Type string` Event type, e.g. 'Normal' or 'Warning'.