CI-deployed agents

Instead of letting the platform build an agent's image, you can build it in your own CI pipeline and deploy the finished image to a workspace with the initializ CLI. The platform never sees your repository or the image internals — your pipeline builds, the platform deploys.

See the CLI deploy reference for pipeline setup and the deploy command.

How a CI deploy works

Each deploy upserts by workspace + agent name: the first deploy creates the agent record, and every later deploy for the same name in the same workspace updates it and rolls the running deployment to the new image. This makes the deploy step idempotent — safe to re-run on every push to your release branch.

A few behaviors worth knowing:

• Same-tag redeploys still roll the workload, so re-pushing a mutable tag (like latest) picks up the new image.
• An image digest can be supplied to pin the exact image content regardless of tag.
• The deploy carries metadata from your repository — declared skills, model, egress, channels — for display and policy purposes. The actual runtime behavior is whatever is baked into your image.
• Metadata tags can be declared in the deploy spec (initializ-deploy.yaml, or per-deploy CLI flags) and are applied to the agent's runtime metadata. The deploy spec is the source of truth: each deploy reconciles the tag set wholesale, so removing a tag from the spec removes it from the agent. The reserved created-by and workspace-id tags are always injected by the platform and can't be set from the spec.
• Raw annotations work alongside tags for keys other tooling reads by exact name (a metrics scraper's prometheus.io/scrape, say): declared in the spec or per-deploy flags, applied verbatim with no namespacing, and reconciled wholesale like tags. Keys under the platform's and Kubernetes' reserved prefixes are rejected, so a raw annotation can never overwrite a platform-owned key. See raw pod annotations.
• The agent's deployment shape follows the spec on every deploy: network reachability, persistent storage, setup steps, and the HTTP invoke declaration all reconcile from what the spec says — declared settings persist across redeploys, and removing one from the spec removes it from the agent on the next deploy.
• CI deploys appear in the console with the same build status and progress logs as platform-built agents, and the agent shows up on the Agents list like any other.

What "managed by CI" means

A CI-deployed agent's configuration is owned by its repository, so the console locks everything that would be baked into the image:

• Locked in the console: skills (including the skill builder and skill edits), model provider, channels, policies, guardrails, and platform-triggered rebuilds. Attempts are rejected — change these in the repo and deploy again from CI.
• Hidden in the console: the Builds card's roll back and Download agent folder actions — a CI agent's folder lives in the repository its CI builds from, and previous images are restored by deploying again from CI.
• Still open in the console: environment values and secret rotation. Rotating a credential patches the agent's secret and restarts it — no new CI run needed.

Everything else about operating the agent is unchanged: health and failure diagnostics, the Activity, Logs, and Usage tabs, Diagnose, chatting from the Overview tab, and participation in workflows.

Network reachability and public exposure

A deployed agent is reachable only inside the platform's cluster by default. The deploy spec's ingress.reachability widens that on request, in three scopes:

• cluster — the default: only other workloads on the platform can call the agent.
• private — the agent gets an endpoint on the organization's internal network (VPC/VPN reach, not the internet).
• public — the agent gets an internet-facing endpoint.

Which of private/public are actually available — and the domain and scheme each maps to — is configured per platform environment by the operator; a deploy naming a mode the environment doesn't offer is rejected with the allowed list. The endpoint's hostname defaults to <agent>-<workspace>.<domain> and can be overridden in the spec.

When an A2A agent is exposed, its Agent Card advertises the exposed URL, so off-cluster callers (external orchestrators, partner systems) discover the right address from the card itself; a cluster-scoped agent's card advertises its internal address. Exposure never weakens inbound auth — bearer verification applies to A2A calls regardless of where they come from.

Reachability follows the spec on every deploy: dropping the ingress block (or setting reachability: cluster) withdraws a previously provisioned endpoint. See the ingress block reference for the full field list and fallback behavior.

The claude-agent runtime

Besides the default runtime, CI can deploy a claude-agent — an agent built on the Claude Agent SDK in your own repository, packaged by your CI into a governed image (initializ agent init scaffolds the project — see the CLI reference). Declare type: claude-agent in the deploy spec; the platform then deploys it with the same governance envelope as any other agent (audit events, runtime policy checks, environment secrets), with a few runtime-specific behaviors:

• Managed model access — the deploy spec names a model provider (anthropic or openai) and model; the platform injects the managed gateway endpoint and credential at deploy time, so the image carries no LLM credentials of its own.
• Optional agent-to-agent exposure — the agent can be exposed to other agents and workflows over the A2A protocol. Inbound calls are bearer-authenticated by default: callers present a platform-issued token, verified against the platform, and only same-workspace callers are accepted. Authentication can be explicitly disabled (a2a.auth: none), and an unrecognized auth value is rejected at deploy rather than shipping an unreachable agent.
• Like every CI-managed agent, its configuration is owned by the repository; environment and secret rotation stay open in the console.

Stateful claude-agents

A claude-agent whose deploy spec declares storage volumes is deployed stateful: the platform provisions persistent storage for each replica and mounts it into the agent, so working state — repository clones, git worktrees, caches — survives restarts and redeploys instead of vanishing with the container filesystem. Declared setup steps (initContainers) run before the agent starts, with the agent's own image and environment and the volumes mounted — the typical pattern is cloning a repository into a volume the agent then works in. Removing the volumes from the spec reverts the agent to a stateless deployment on the next deploy. See the storage reference.

HTTP-invoked claude-agents

Not every agent speaks A2A. A claude-agent that serves a plain HTTP route of its own — a webhook receiver, a manual-trigger endpoint — declares it in the deploy spec's http block, and the platform treats the agent as HTTP-invoked (an agent is A2A or HTTP-invoked, never both). The console then shows the endpoint URL and path on the agent's Settings and renders an invoke form — typed fields when the spec carries an input schema, a raw JSON body otherwise.

When an HTTP-invoked agent is exposed beyond the cluster, the platform authenticates every call to the declared invoke path before it reaches the agent: callers present a platform-issued token, the platform verifies it (any valid token of the agent's organization is accepted — including an operator invoking from the console), and each verification lands in the agent's audit trail. Routes the agent serves besides the declared path — health checks, webhooks that carry their own signature verification — pass through untouched, so self-authenticating integrations keep working. See the HTTP invoke reference.

What the platform records for every run

A governed claude-agent reports into the same observability surfaces as any platform-built agent — per run, not per process:

• One timeline per run. Each A2A task (and each run of a long-running worker) appears as its own invocation timeline in the agent's Activity and the Security events view, rather than every run folding into one endless process-level stream. Lifecycle events — inbound auth (with the calling user's identity), session start, request, response, completion — bracket every run, including failed ones: a task that errors still closes its timeline with the failure recorded.
• A populated executions list. Every task is pushed to the platform's session store, so the agent's execution list and per-run transcript in the console fill in just like a platform-built agent's.
• End-to-end correlation. The A2A task id is handed to the skill handling the task and stamped on the run's audit events, so everything a task did — model calls, tool calls, the response — correlates under one id from the caller's request to the last event.
• Accurate token accounting. Every model call's usage is recorded with full token detail, including cached input tokens — totals count cache reads and writes, not just the uncached delta — and each call is attributed to its model and provider, so the Usage tab buckets claude-agent inference correctly instead of showing a blank provider.
• Model-id portability. An agent hard-coded to Bedrock-style Anthropic model ids runs unchanged against the platform's managed Anthropic gateway — the ids are translated automatically, so adopting the managed gateway needs no source change.