Cookbook

AML is easiest to learn by building a workflow with a clear job to do. This cookbook moves from a credential-free review pipeline to typed outputs, application <Tool /> capabilities, scoped <Mcp /> access, filesystem resources, durable provider composition, and operational jobs.

Recommended path

Start with Build a code-review workflow. It demonstrates bounded filesystem evidence, a real Skill, typed specialist Agents, explicit parallelism, application validation, and synthesis without requiring model credentials by default.

Before you begin

Every recipe assumes:

• Node.js >=26;
• dependencies installed with npm install;
• TypeScript/TSX support with AML’s automatic JSX runtime;
• the public application entrypoint, @aml-jsx/sdk.

The complete recipe files construct and evaluate their own AmlRuntime, which is the clearest shape when an application owns limits, defaults, telemetry, and shutdown. To run a workflow with the experimental CLI instead, export the AML tree, put required providers directly on their components, and use npx aml run ./workflow.tsx. Do not wrap a second AmlRuntime inside the exported CLI entry.

The recipe status tells you what the source actually does:

• Deterministic uses @aml-jsx/sdk/testing and needs no model, credentials, or network.
• Credentialed starts a real Agent adapter or expects provider credentials and an executable.
• Resource-backed exercises a local, container, or remote filesystem/execution boundary. Read its mutation and isolation notes before running it.

Recipe steps and claims are verified against the implementation and specification links in each page’s API and source links section.

Learn the workflow shape

Auto-author a changelog with AMLCompose deterministic commit collection, repository investigation, editorial writing, and a validated document update.

Build a code-review workflowMaterialize bounded evidence, register a real Skill, collect typed specialist findings, validate them, and synthesize a review.

Return structured outputValidate a provider response with a Standard Schema and pass the typed finding into a later .

Define and grant a JavaScript ToolCreate a schema-backed callable, use it from application code, and grant it explicitly when an Agent needs the capability.

Recipe	Status	Needs	Best for
Auto-authored changelog	Credentialed + repository-backed	Script collector, Agent provider, schemas, and a document writer	Composable Agents around deterministic release work
Code-review workflow	Deterministic by default; credentialed by opt-in	Node, SDK, zod; provider executable and credentials only for OpenCode/Codex modes	A first useful multi-Agent workflow
Structured output	Deterministic	Node, SDK, zod	Typed findings and validation boundaries
Tools	Deterministic	Node, SDK/testing, zod	Application-owned functions and capability scoping

Add capabilities and resources

Test capabilities and resourcesRun a complete workflow with runtime-level testing providers, inspect normalized calls, and spy on resource lifecycle hooks.

Model Context Protocol capabilitiesLearn MCP descriptor validation and Agent scoping. The included example URL is fixture metadata; this recipe makes no connection.

Combine Sandboxes and WorkspacesMaterialize files in a temporary local Workspace, narrow an execution Sandbox, and understand trusted-host boundaries.

Run AML in a Sandbox imageStart AML's recommended image through Docker, run commands inside it, and pin or replace the image deliberately.

Choose between a Tool and MCPCompare ownership, transport, credentials, failure modes, and host-process security with complete examples of both.

Recipe	Status	Needs	Best for
Testing AML workflows	Deterministic	Node, SDK/testing, Vitest	Replacing runtime defaults and asserting capability/resource behavior
MCP capabilities	Deterministic fixture	Node, SDK/testing; no MCP server or credentials	Capability isolation without pretending to run an external server
Tool or MCP?	Deterministic Tool + credentialed MCP example	Node and SDK; OpenCode, credentials, and an operated MCP server for the MCP path	Choosing the correct capability boundary
Sandbox image	Resource-backed	Node, SDK, Docker, and AML Agent Sandbox	Understanding image defaults and overrides
Sandboxes and Workspaces	Deterministic + resource-backed	Node, SDK/testing, writable temp directory	Local file materialization and execution-scope composition
Generated diagnostics	Deterministic Agent + resource-backed	Node, SDK/testing, Docker, and the selected interpreter image	Treating generated code as data before explicit execution

Resource-backed is not the same as isolated

localSandbox() executes trusted host processes. The Sandbox/Workspace recipe uses a temporary directory for a deterministic walkthrough; it is not a hostile-code security boundary. For stronger isolation, compare the actual Docker, Daytona, and Modal provider contracts in the provider docs.

Compose and operate real jobs

Operate AML in a background jobSet explicit runtime budgets, propagate cancellation, and emit content-minimizing traces around a real OpenCode Agent provider.

Stop a CLI workflow safelyInterrupt a real process tree and follow CLI cancellation through Sandbox release to the conventional exit status.

Observe a live Agent sessionBuild an ordered activity feed from Agent turn spans and unchanged ACP updates across two FollowUps.

Correlate application observabilityTime custom phases and retrieve run-keyed summaries across overlapping evaluations.

Compose Codex, Docker, and S3Follow one production skeleton across a credentialed Agent, disposable container, and durable revisioned Workspace.

Route typed data safelyValidate a model-shaped route, canonicalize it, enforce root containment, and only then construct the selected Workspace.

Recipe	Status	Needs	Best for
Production job	Credentialed + deployment shape	Node/ESM TSX runtime, OpenCode executable, model configuration, credentials, and a logger	Background jobs that need bounded execution and operational controls
CLI process safety	Resource-backed, credential-free	POSIX host, local Sandbox, CLI, and one terminal interrupt	Graceful signal handling and process-tree cleanup
Agent activity	Credentialed	OpenCode executable, model credentials, and an approved content-capturing terminal	Understanding live ACP activity across Agent turns
Application observability	Deterministic	Node, SDK, and application request context	Custom phase timing and concurrent run correlation
Codex + Docker + S3	Credentialed + container + durable storage	Codex ACP image, Docker, model credentials, S3 bucket, and AWS identity	Understanding the complete three-provider lifecycle
Structured routing	Deterministic	Node, SDK/testing, zod, and an application-owned root directory	Safely turning model-shaped data into resource selection

This recipe is intentionally provider-backed. It does not install OpenCode, provision credentials, define a deployment image, or make local execution safe for untrusted code. Treat the code as a composition-root pattern and inject the Sandbox/Workspace providers required by your deployment.

Control a session’s authored turns

Use deliberate editorial passes with FollowUp when several authored instructions should run in one provider session. The recipe explains what AML guarantees, what conversation history remains provider-owned, and when separate evaluations are clearer.

Recipe format

Each page follows the same reading order:

1. Goal — the user task and the AML shape it produces.
2. Prerequisites — credentials, executables, packages, and resource requirements.
3. Complete source — imports included, with provider assumptions visible.
4. Run and expected output — what is safe to execute and what success looks like.
5. How it works — the runtime contract behind the example.
6. Failure and security notes — boundaries that should affect production decisions.
7. API and source links — public contracts and the maintained repository example.

For the repository’s current runnable catalog, use the command on the Examples page. The runner remains the source of truth; the docs recommend paths by learning goal instead of maintaining a second export inventory.