Documentation | Build

Build

BuildResource

Methods

client.build.create() ->

post/v5/builds

Submit a container image build from an uploaded build context and return the created build record.

The request is multipart form data: a tar.gz context_archive with the Dockerfile at its root is streamed to cloud object storage, along with the target image_name, an optional image_tag (defaults to latest), optional Docker build_args supplied as a JSON string, and an optional target platform. Exactly one of agent_name or agent_id must be provided: pass agent_name to create a brand-new agent for a first-time build (rejected if an agent with that name already exists), or agent_id to build for an agent that already exists. The build is handed to the configured cloud build provider and runs asynchronously, so the returned record reflects the build's initial status (typically queued or running) rather than a finished image; poll Get Build or follow Stream Build Logs to observe progression to a terminal state. The request is rejected if the archive is missing or empty, exceeds 500MB, or if build_args is not valid JSON.

client.build.retrieve() ->

AgentexCloudBuild

get/v5/builds/{build_id}

Retrieve a single build by its ID, including its current lifecycle status.

Because builds run asynchronously after submission, the status returned here reflects the latest known state and may still be queued or running; call this endpoint again to observe progression to a terminal state such as success, failed, cancelled, or timed out. Responds with a not-found error if no such build exists for the caller's account.

Parameters

build_id: str

Returns

AgentexCloudBuild

id: str

The unique identifier of the entity.

account_id: str

The ID of the account that owns the given entity.

agent_name: str

The name of the agent that this build belongs to

build_status: Literal["queued", "running", "success", "failed", "cancelling", "cancelled", "deleting", "delete_failed", "timed_out", "error", "unknown"]

The current build lifecycle status

cloud_provider_build_id: str

The unique identifier of the build from the cloud provider, or an internal UUID when an existing image is copied without a provider build.

created_at:

datetime

(format: date-time)

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

created_by:

Identity

The identity that created the entity.

image_name: str

The name of the container image to build.

image_tag: str

The tag for the container image.

source_commit: Optional[str]

Git commit the build context was at, when a git work tree.

source_dirty: Optional[bool]

Whether the work tree had uncommitted changes at build time (null outside git).

source_ref: Optional[str]

Git branch or tag for source_commit, when resolvable.

source_repo: Optional[str]

Normalized git remote the build context came from (host/path, no credentials).

source_subpath: Optional[str]

Build-context path relative to the repo root (which agent, in a monorepo).

working_tree_hash: Optional[str]

Deterministic SHA-256 content hash of the build inputs (not the tarball).

agent_id: Optional[str]

The UUID of the agent that this build belongs to

build_end_time: Optional[datetime]

(format: date-time)

When the cloud provider finished the build

build_start_time: Optional[datetime]

(format: date-time)

When the cloud provider started the build

image_url: Optional[str]

The URL of the container image. This is not guaranteed to be present until the build is complete.

object: Optional[Literal["agentex_cloud_build"]]

(default: "agentex_cloud_build")

Request example

import os
from scale_gp_beta import SGPClient

client = SGPClient(
    api_key=os.environ.get("SGP_API_KEY"),  # This is the default and can be omitted
)
agentex_cloud_build = client.build.retrieve(
    "build_id",
)
print(agentex_cloud_build.id)

200Example

{
  "id": "id",
  "account_id": "account_id",
  "agent_name": "agent_name",
  "build_status": "queued",
  "cloud_provider_build_id": "cloud_provider_build_id",
  "created_at": "2019-12-27T18:11:19.117Z",
  "created_by": {
    "id": "id",
    "type": "user",
    "object": "identity"
  },
  "image_name": "image_name",
  "image_tag": "image_tag",
  "source_commit": "source_commit",
  "source_dirty": true,
  "source_ref": "source_ref",
  "source_repo": "source_repo",
  "source_subpath": "source_subpath",
  "working_tree_hash": "working_tree_hash",
  "agent_id": "agent_id",
  "build_end_time": "2019-12-27T18:11:19.117Z",
  "build_start_time": "2019-12-27T18:11:19.117Z",
  "image_url": "image_url",
  "object": "agentex_cloud_build"
}

client.build.list() -> SyncCursorPage[

AgentexCloudBuild

]

get/v5/builds

List container image build records for the caller's account as a paginated collection.

Each entry is one individual build with its current lifecycle status; pass agent_name, source_commit, or working_tree_hash to return only matching builds. Archived builds are excluded, and results are limited to builds the caller is permitted to read. Use this to enumerate individual builds; to instead list agents that have been built but not yet deployed, use GET /v5/builds/undeployed.

client.build.logs() ->

StreamChunk

get/v5/builds/{build_id}/logs

Stream a build's logs as Server-Sent Events.

The response has content-type text/event-stream; each event carries one log line as an AgentexCloudBuildLogLine object, delivered as lines become available from the cloud build provider. The stream ends when the provider stops producing output. Responds with a not-found error if no such build exists for the caller's account.

client.build.cancel() ->

AgentexCloudBuild

post/v5/builds/{build_id}/cancel

Request cancellation of a build and return 202 Accepted.

Cancellation runs asynchronously: the endpoint verifies the build exists and then hands it off to a background workflow that marks the build as cancelling, asks the cloud build provider to stop it, and polls until the build reaches a terminal state before recording the final status. Only builds that are still queued or running are actually cancelled; if the build has already finished, or cancellation is already in progress, the request is still accepted but has no effect. The returned record reflects the build's state at the time of the call, so it will not yet show the pending cancellation. The request is rejected if no such build exists for the caller's account.

client.build.list_undeployed() ->

BuildListUndeployedResponse

get/v5/builds/undeployed

List agents that exist only as cloud builds and have no healthy deployment yet.

Unlike listing builds, this aggregates by agent: it returns one entry per distinct agent name whose builds have never reached a healthy deploy, each carrying that agent's most recent build and its total build count. The result is a plain list (not paginated) and is limited to builds the caller is permitted to read. Use this to surface agents that were built but still need to be deployed; use GET /v5/builds when you need the individual build records instead.

Domain types

class AgentexCloudBuild: ...

List[

BuildListUndeployedResponseItem

]

class StreamChunk: ...

A single log line from the build process.