Documentation / Agents / Deploy

Deploy an Agent

Build and update an Agent from an archive or pinned Git commit.

Before you begin

Prepare a project directory, ZIP or TAR.GZ package, or a public HTTPS Git repository with a full 40-character commit SHA. Native Constal packages declare an Agent manifest. Existing Mastra, LangGraph, OpenAI SDK, and Claude Managed Agents SDK projects use their normal entrypoints and do not add a Constal manifest or replace framework imports. See Deploy a Mastra project, Deploy OpenAI Agents SDK projects, and Deploy Claude Managed Agents SDK projects.

Steps

  1. For a native package, author and type-check the Agent. For Mastra, retain the existing package.json, lockfile, and exported Mastra instance; do not install @constal/sdk merely to deploy it.
  2. Open Agents and choose Deploy Agent.
  3. Select Package archive or Git repository. Supply the ZIP or TAR.GZ archive, or enter a public repository URL and immutable 40-character commit.
  4. Review the expected Resource kind and deployment guidance, then choose Deploy.
  5. The equivalent Platform API operation is POST /v1/deployments with the raw archive, Bearer deployment authority, correct content type, and a caller-stable Idempotency-Key.
  6. Poll GET /v1/deployments/:deploymentId while Constal validates the archive, type-checks the SDK contract, builds and verifies the immutable executable artifact, and safely activates the requested revision.
  7. Open the resulting Agent detail page.
sh
curl https://platform.constal.ai/v1/deployments \
  -H "Authorization: Bearer $CONSTAL_DEPLOYMENT_KEY" \
  -H "Idempotency-Key: support-agent-1.0.0" \
  -H "Content-Type: application/zip" \
  --data-binary @support-agent.zip

Redeploy the same Agent id whenever its code or configuration changes. You can omit version or reuse its label; changed content does not require a version bump. By default, an immediate deployment updates the Agent without an expected revision. Supply expectedCurrentDeploymentRevision only when you want a deployment precondition. Historical deployment records remain available, and running Sessions continue using their accepted code.

Deploy an Agent with a UI

A native Agent manifest may declare its web interface inline with a ui block (id, displayName, source, channel, and optional access, execution, limits, labels). The same deployment builds the Agent, packages the source directory as a constal.ui.v1 bundle, stores it as an immutable artifact, and publishes a ui Resource whose target.agent is exactly the Agent revision that deployment produced. The Agent and its UI are promoted together or not at all: a UI failure fails the deployment before the Agent current pointer moves, and a stale UI current pointer fails the deployment without moving either pointer.

The deployment record lists both Resources under outputs: ordinal 0 is the Agent and ordinal 1 is the UI, whose resource.url is the public address. Top-level resourceCrn and resourceHash remain the Agent's.

sh
constal deploy . --wait --output json | jq -r '.outputs[] | select(.resourceKind == "ui") | .resource.url'

Redeploying re-pins the UI to the new Agent revision while its route and URL stay stable. Removing the block leaves the published UI untouched; delete it explicitly through the Resource API. Manifests with a ui block support only immediate rollouts: --rollout canary and candidate builds are rejected, so publish such a UI through the standalone Resource API instead. See Dynamic UIs for the bundle layout.

Canary a revision

Use a canary when production evidence should precede activation. The deployment builds and runs every declared Replay gate normally, but keeps the current Agent pointer unchanged. Eligible new Sessions are assigned deterministically to the candidate or control revision; an existing Session remains pinned to the revision it started with.

sh
constal deployments create support-agent.zip \
  --rollout canary \
  --fraction 0.05 \
  --tags '{"plan":"enterprise"}'

A canary is rejected for an Agent manifest that declares a ui block; publish that UI through the standalone Resource API instead. fraction must be greater than zero and less than one. tags is an optional exact-match selector over invocation tags. The eval door receives immutable constal.rollout.id and constal.rollout.cohort tags, allowing the same live Scorers to sample candidate and control traffic without delaying either cohort.

Read the rollout, review its evaluation evidence, then make an explicit idempotent decision:

sh
constal agents rollout get support
constal agents rollout promote support \
  --deployment 123e4567-e89b-42d3-a456-426614174000 \
  --reason "paired quality scores improved"

Use agents rollout rollback with the same arguments when the candidate regresses. Promotion atomically moves the current pointer from the exact control hash to the candidate hash. Rollback leaves the control pointer untouched. A stale control pointer, concurrent deployment, reused event ID with different intent, or unavailable candidate fails closed.

Verify

Confirm the deployment reports an immutable revision, executable artifact, code digest, successful probe, and rollout state. The detail page should show the expected canonical CRN, Agent version, execution mode, Resource bindings, Policies, Tool catalog, and limits. Start a small Run and check that its journal records the assigned deployment revision and rollout cohort.

Next steps

Continue with Operate Agents, or Start a Run to test the deployment.