> ## Documentation Index
> Fetch the complete documentation index at: https://evalgate.com/docs/llms.txt
> Use this file to discover all available pages before exploring further.

# Deployable Assets

> Invoke approved prompt, scorer, tool, workflow, and agent-entrypoint versions with exact provenance, controlled rollout, and atomic rollback.

Deployable Assets turns an immutable EvalGate release version into a governed runtime endpoint. Each deployment binds one asset to one environment (`dev`, `staging`, or `prod`) and keeps an exact serving version, policy snapshot, rollout assignment, revision, and evidence history.

Use this control plane when an asset has passed offline evaluation and must serve application traffic without losing the connection between the request, release version, model-gateway call, cost, policy decision, and rollout state.

## Supported assets

The same deployment contract applies to five release kinds:

| Kind               | Typical payload                                  | Runtime guarantee                                                 |
| ------------------ | ------------------------------------------------ | ----------------------------------------------------------------- |
| `prompt`           | Messages, model configuration, and variables     | Input variables and structured output are schema checked          |
| `scorer`           | Model-backed or instruction-based score contract | Exact scorer version and gateway call are recorded                |
| `tool`             | Tool instruction and typed arguments             | The registered gateway and data policy remain mandatory           |
| `workflow`         | Versioned orchestration instruction              | The workflow entry version is fixed for the invocation            |
| `agent_entrypoint` | Agent system instruction and typed request       | The exact entrypoint, model call, and rollout cohort are retained |

All deployable versions require a SHA-256 content hash and object input/output schemas. A deployment never resolves a mutable “latest” alias.

## Permissions

| Operation                                                                       | Required access                             |
| ------------------------------------------------------------------------------- | ------------------------------------------- |
| List deployments and evidence                                                   | `runs:read`                                 |
| Invoke a deployment                                                             | `runs:write`                                |
| Approve, deploy, configure rollout, record health, pause, promote, or roll back | Organization administrator with `admin:org` |

API keys can invoke only when their organization and scopes match the deployment. An approval in one environment never authorizes another environment.

## Prepare a release version

A release version payload contains a runtime and JSON object schemas:

```json theme={null}
{
  "runtime": {
    "provider": "openai",
    "model": "gpt-4.1-mini",
    "systemPrompt": "You are a support specialist.",
    "instruction": "Answer the support request using only supplied facts.",
    "maxTokens": 800,
    "temperature": 0
  },
  "inputSchema": {
    "type": "object",
    "required": ["ticket", "facts"],
    "properties": {
      "ticket": { "type": "string" },
      "facts": { "type": "array" }
    },
    "additionalProperties": false
  },
  "outputSchema": {
    "type": "object",
    "required": ["text"],
    "properties": { "text": { "type": "string" } },
    "additionalProperties": false
  }
}
```

The runtime calls the organization model gateway. Deployable invocation does not contain a direct-provider fallback or a caller-supplied egress URL.

## Approve and deploy

First approve the exact version for the target environment:

```bash theme={null}
curl -X POST "$EVALGATE_URL/api/deployable-assets/approvals" \
  -H "Authorization: Bearer $EVALGATE_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "artifactVersionId": 128,
    "environment": "prod",
    "rationale": "Release gate EG-482 passed with security review"
  }'
```

Then create the environment deployment:

```bash theme={null}
curl -X POST "$EVALGATE_URL/api/deployable-assets" \
  -H "Authorization: Bearer $EVALGATE_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "artifactId": 42,
    "artifactVersionId": 128,
    "environment": "prod",
    "rationale": "Initial production release",
    "policy": {
      "rateLimitPerMinute": 1200,
      "dailyBudgetUsd": 250,
      "maxCostPerInvocationUsd": 0.50,
      "maxInputBytes": 65536,
      "dataClassification": "internal",
      "allowedInputClassifications": ["public", "internal"]
    }
  }'
```

There is one deployment record per asset and environment. The database rejects an unapproved version, a version from another organization or artifact, a non-deployable kind, or a version without an immutable content hash.

## Invoke an exact deployment

```bash theme={null}
curl -X POST "$EVALGATE_URL/api/deployable-assets/$DEPLOYMENT_ID/invoke" \
  -H "Authorization: Bearer $EVALGATE_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "idempotencyKey": "ticket-T-482-attempt-1",
    "requestKey": "customer-2048",
    "inputClassification": "internal",
    "stream": true,
    "input": {
      "ticket": "T-482",
      "facts": ["Plan is Pro", "Renewal is 2026-08-01"]
    }
  }'
```

`idempotencyKey` is unique within the deployment. Repeating it returns the original invocation instead of creating a second gateway call or charge. `requestKey` controls deterministic canary assignment; use a stable customer, conversation, or session key when cohort stickiness matters.

When `stream` is true, the response contains ordered partial evidence:

1. `version`: exact artifact version and cohort chosen before execution.
2. `output`: schema-validated serving output.
3. `evidence`: the model-gateway call identifier.

Each durable invocation contains:

* organization, deployment, artifact, exact version, environment, and cohort;
* input and output hashes plus the schema-validated values;
* gateway model-call ID, request/response hashes, latency, and token usage;
* reported or explicitly unavailable cost source plus the budget reservation;
* deployment and gateway policy snapshots;
* shadow version, model call, and output hash when shadowing is enabled.

Unknown gateway cost is never presented as zero. The configured maximum per-invocation amount is reserved before the gateway call, so missing cost data cannot silently bypass the daily budget.

## Policy enforcement order

Before gateway execution, EvalGate verifies:

1. caller authentication, organization, and `runs:write` scope;
2. deployment status and immutable environment/version binding;
3. idempotency replay;
4. serialized input size and allowed data classification;
5. per-minute request count;
6. atomic daily budget reservation;
7. input schema.

Gateway output is checked against the release output schema before it can be marked successful. Blocked and failed attempts retain evidence and never masquerade as successful invocations.

## Canary rollout

Approve the candidate for the same environment, then assign a bounded percentage:

```bash theme={null}
curl -X POST "$EVALGATE_URL/api/deployable-assets/$DEPLOYMENT_ID/rollout" \
  -H "Authorization: Bearer $EVALGATE_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "versionId": 129,
    "mode": "canary",
    "trafficPercent": 10,
    "rationale": "Ten-percent online quality comparison"
  }'
```

Assignment hashes the deployment ID and request key into a stable bucket. A request cannot randomly move between serving and canary cohorts while its key remains the same.

## Shadow rollout

Shadow mode evaluates the candidate for every serving request but never changes the serving output:

```bash theme={null}
curl -X POST "$EVALGATE_URL/api/deployable-assets/$DEPLOYMENT_ID/rollout" \
  -H "Authorization: Bearer $EVALGATE_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "versionId": 129,
    "mode": "shadow",
    "trafficPercent": 100,
    "rationale": "Silent production comparison before canary"
  }'
```

Partial shadow percentages are rejected. A failed shadow call is recorded in trace evidence and does not fail or replace a valid serving response.

## Health evidence and promotion

Health windows are cohort- and version-bound. Submit the same interval for serving and canary cohorts with invocation volume, success, quality, p95 latency, cost, and policy violations.

```bash theme={null}
curl -X POST "$EVALGATE_URL/api/deployable-assets/$DEPLOYMENT_ID/health" \
  -H "Authorization: Bearer $EVALGATE_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "versionId": 129,
    "cohort": "canary",
    "windowStartedAt": "2026-07-13T10:00:00Z",
    "windowEndedAt": "2026-07-13T11:00:00Z",
    "invocationCount": 1000,
    "successRate": 0.998,
    "qualityScore": 0.934,
    "p95LatencyMs": 286,
    "costUsd": 18.42,
    "policyViolationCount": 0
  }'
```

Promotion requires comparative serving and canary evidence, at least 95% canary success, no policy violations, and canary quality no more than 0.02 below serving quality. The transition atomically moves the canary to active, stores the old active version as the rollback target, clears canary assignment, increments the revision, and appends an audit event.

```bash theme={null}
curl -X PATCH "$EVALGATE_URL/api/deployable-assets/$DEPLOYMENT_ID" \
  -H "Authorization: Bearer $EVALGATE_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "action": "promote",
    "expectedRevision": 4,
    "rationale": "Canary met online quality, reliability, cost, and policy gates"
  }'
```

## Pause, resume, and rollback

Every control-plane transition includes `expectedRevision`. If another operator changes the deployment first, EvalGate returns a conflict and requires a refresh instead of overwriting the newer decision.

Pause immediately blocks new invocations. Resume preserves the current exact active version. Rollback swaps the active and recorded previous versions inside one database transaction and clears in-progress canary assignment:

```bash theme={null}
curl -X PATCH "$EVALGATE_URL/api/deployable-assets/$DEPLOYMENT_ID" \
  -H "Authorization: Bearer $EVALGATE_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "action": "rollback",
    "expectedRevision": 5,
    "rationale": "Quality regression in the post-promotion observation window"
  }'
```

Rollback never resolves a new candidate. It selects only the exact previous version captured during promotion, revalidates its environment approval, and records both version IDs and revisions.

## Operator workspace

Open **Deployable Assets** from the EvalGate navigation to:

* compare active, canary, shadow, and paused environments;
* inspect immutable hashes and policy budgets;
* approve and deploy an exact version;
* configure canary or shadow rollout;
* compare quality, reliability, latency, cost, and violations by cohort;
* inspect exact invocation and model-call provenance;
* promote a healthy canary, pause/resume traffic, or confirm an atomic rollback;
* follow the revisioned rollout history and rationale.

The workspace includes loading, empty, inline error, disabled-action, and destructive confirmation states. Tables remain horizontally scrollable at narrow widths, and all controls retain keyboard focus indicators.

## Troubleshooting

| Response             | Meaning                                                              | Resolution                                                                    |
| -------------------- | -------------------------------------------------------------------- | ----------------------------------------------------------------------------- |
| `403`                | Caller lacks the required scope or administrator role                | Use an organization-scoped key or administrator session                       |
| `409`                | Deployment revision changed or the requested transition is not valid | Refresh inventory and retry with the current revision                         |
| `412`                | Canary lacks comparative health evidence                             | Record matching serving/canary windows and resolve quality or policy failures |
| `422 UNAPPROVED`     | Version is not approved for the target environment                   | Approve that exact version and environment                                    |
| `422 SCHEMA_INVALID` | Input or gateway output violates the release schema                  | Fix the request or release contract; do not widen schema silently             |
| `423 PAUSED`         | Environment is paused                                                | Resume only after the incident or policy review is complete                   |
| `429 POLICY_DENIED`  | Rate, budget, size, or data policy rejected the request              | Inspect the persisted policy decision and adjust traffic or approved policy   |