# Production readiness

The operational checklist and deployment model for running AML workflows reliably.
Canonical: https://agent-markup-language.com/docs/production/
Documentation index: https://agent-markup-language.com/docs/
Complete documentation: https://agent-markup-language.com/docs/llms.txt

AML can execute ordinary host processes, disposable containers, or remote Sandboxes and can persist Workspaces locally or in object storage. Production readiness therefore depends on the combination of providers, the credentials they receive, and the effects your workflow is allowed to perform.

This section is a set of production guidance pages, not a generic security certification. Read the provider caveats before selecting an execution boundary.

## Choose the right page

| You need to…                                                 | Read                                                                                                   |
| ------------------------------------------------------------ | ------------------------------------------------------------------------------------------------------ |
| establish a threat model and protect credentials             | [Security](https://agent-markup-language.com/docs/production/security/)                                                                 |
| package AML into a service, worker, or job                   | [Deployment](https://agent-markup-language.com/docs/production/deployment/)                                                             |
| operate retries, cancellation, locks, and traces             | [Operations](https://agent-markup-language.com/docs/production/operations/)                                                             |
| diagnose a live cleanup, lock, publication, or trace failure | [Incident response](https://agent-markup-language.com/docs/production/incident-response/)                                               |
| understand the provider-specific trade-offs                  | [Sandbox providers](https://agent-markup-language.com/docs/providers/sandboxes/) and [Workspace providers](https://agent-markup-language.com/docs/providers/workspaces/) |
| understand how AML provider adapters are structured          | [Provider engineering](https://agent-markup-language.com/docs/provider-authoring/)                                                      |
| implement a new adapter against the public TypeScript API    | [Provider authoring reference](https://agent-markup-language.com/docs/reference/provider-authoring/)                                    |

## The production topology

```text
application process
  ├─ AmlRuntime: limits, cancellation, traces, scheduling
  ├─ Agent provider: model harness and session protocol
  ├─ Sandbox provider: process environment and execution policy
  └─ Workspace provider: materialization, locking, revisions, persistence
                    │
                    ├─ local host directory
                    ├─ Docker bind mount
                    └─ remote Sandbox + transferred Workspace
```

AML does not make these four responsibilities interchangeable. An Agent can be provider-neutral at the authored boundary while still requiring a particular executable, image, model credential, or Sandbox runtime. A remote Sandbox may make execution ephemeral while the Workspace remains durable. A local Workspace may persist directly in the application’s filesystem without creating a revision history.

## Grow the deployment one boundary at a time

| Stage                  | Add                                                               | What you prove before moving on                                                    |
| ---------------------- | ----------------------------------------------------------------- | ---------------------------------------------------------------------------------- |
| Deterministic workflow | Testing provider and ordinary TypeScript policy                   | Tree shape, dataflow, schemas, budgets, and expected application output.           |
| Live Agent             | One coding harness, model, and credential path                    | Executable discovery, authentication, capability translation, and cancellation.    |
| Ephemeral execution    | Docker, Daytona, or Modal Sandbox                                 | Image contents, cwd mapping, process cleanup, access, and resource/network policy. |
| Durable state          | Local, Filesystem, or S3 Workspace                                | Materialization, conflicts, save policy, publication, retention, and recovery.     |
| Production job         | Request deadlines, identity, redacted telemetry, and retry policy | The exact complete graph survives failure and cleanup paths.                       |

Do not introduce all three provider boundaries to debug a first Agent call. Each stage has an independently observable contract and failure surface.

## A deployable runtime baseline

The runtime defaults include bounded Agent calls and concurrency, depth and Loop limits, and a trace sink that excludes sensitive content unless a consumer explicitly opts in. Set the values deliberately for your workload and pass cancellation per evaluation.

```tsx
import {
  Agent,
  AmlRuntime,
  Sandbox,
  Workspace,
  codexAgent,
  createConsoleTracer,
  dockerSandbox,
  s3Workspace,
} from "@aml-jsx/sdk"

function requireEnv(name: string): string {
  const value = process.env[name]
  if (!value) throw new Error(`${name} is required`)
  return value
}

const runtime = new AmlRuntime({
  agentProvider: codexAgent({ apiKey: requireEnv("OPENAI_API_KEY") }),
  sandboxProvider: dockerSandbox({
    image: requireEnv("AML_AGENT_IMAGE"),
  }),
  workspaceProvider: s3Workspace({
    bucket: requireEnv("AML_WORKSPACE_BUCKET"),
    prefix: "production/workspaces",
  }),
  maxAgentCalls: 32,
  maxConcurrentAgents: 4,
  maxTurnsPerAgent: 8,
  trace: createConsoleTracer({ captureContent: false }),
})

const workflow = (
  <Workspace id="review-42" load={false} save={{ on: "success", retention: 5 }}>
    <Sandbox access="read-write">
      <Agent>Review the materialized project and write reports/summary.md.</Agent>
    </Sandbox>
  </Workspace>
)

const controller = new AbortController()
const stop = setTimeout(() => controller.abort(new Error("request deadline exceeded")), 120_000)

try {
  await runtime.evaluate(workflow, { signal: controller.signal })
} finally {
  clearTimeout(stop)
}
```

This is a wiring example, not a claim that the image or credentials are ready. The image must contain the selected ACP executable and its dependencies; the object-storage identity must have the permissions required by the [S3 Workspace](https://agent-markup-language.com/docs/providers/workspaces/s3/) protocol; and the application must decide whether model-generated actions are trusted.

## Readiness gates

Before production traffic, verify each gate with the exact provider combination you will deploy:

1. **Identity** — credentials are injected by the workload identity or secret manager, not written into prompts, Workspaces, images, or setup strings.
2. **Execution** — the selected Sandbox has the required shell, utilities, ACP executable, model configuration, network policy, and resource limits.
3. **Persistence** — the Workspace’s load, save, lock, retention, and conflict behavior matches the retry and concurrency model.
4. **Cancellation** — request deadlines abort evaluation work; providers attempt cleanup, which may continue after cancellation and can itself fail. Confirm process, temporary-directory, remote-Sandbox, and lock outcomes.
5. **Observability** — traces correlate a run and its spans without capturing customer content by default; provider and cleanup failures reach an operational sink.
6. **Recovery** — retries distinguish active-writer conflicts, stale conditional publication, provider outages, model failures, and completed external side effects.

## Support and maturity

The current providers are shipped built-ins in a pre-stable SDK. “Built-in” does not mean every combination has identical capabilities or that a vendor environment is continuously certified. Check the provider pages for requirements and compatibility:

- [Agent providers](https://agent-markup-language.com/docs/providers/agents/) use ACP for the built-in coding-agent integrations.
- [Sandbox providers](https://agent-markup-language.com/docs/providers/sandboxes/) differ in read-only behavior, transfer semantics, cancellation, and deployment-owned security posture.
- [Workspace providers](https://agent-markup-language.com/docs/providers/workspaces/) differ in direct materialization versus revision-backed persistence.

Treat a provider combination as production-ready only after exercising its actual image, credentials, network, filesystem, and failure paths. An adapter that passes structural validation has proved its API shape; it has not proved vendor availability, credentials, or a hostile-code threat model. The [compatibility guide](https://agent-markup-language.com/docs/compatibility/) defines the narrower evidence labels used throughout these docs.

## Related concepts

- [AML evaluation model](https://agent-markup-language.com/docs/concepts/)
- [Runtime limits and errors](https://agent-markup-language.com/docs/runtime/)
- [Observability](https://agent-markup-language.com/docs/observability/)
- [Incident response](https://agent-markup-language.com/docs/production/incident-response/)
- [Provider engineering](https://agent-markup-language.com/docs/provider-authoring/)
- [Provider authoring reference](https://agent-markup-language.com/docs/reference/provider-authoring/)
- [Shared provider contracts](https://agent-markup-language.com/docs/reference/providers/)