# Cookbook

Task-oriented AML recipes for building workflows, capabilities, resource boundaries, and production jobs.
Canonical: https://agent-markup-language.com/docs/cookbook/
Documentation index: https://agent-markup-language.com/docs/
Complete documentation: https://agent-markup-language.com/docs/llms.txt

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 />`](https://agent-markup-language.com/docs/reference/primitives/tool/) capabilities, scoped [`<Mcp />`](https://agent-markup-language.com/docs/reference/primitives/mcp/) access, filesystem resources, durable provider composition, and operational jobs.

**Tip — Recommended path**

Start with [Build a code-review workflow](https://agent-markup-language.com/docs/cookbook/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](https://agent-markup-language.com/docs/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 AML](https://agent-markup-language.com/docs/cookbook/changelog-maintainer/) — Compose deterministic commit collection, repository investigation, editorial writing, and a validated document update.

- [Build a code-review workflow](https://agent-markup-language.com/docs/cookbook/code-review-workflow/) — Materialize bounded evidence, register a real Skill, collect typed specialist findings, validate them, and synthesize a review.

- [Return structured output](https://agent-markup-language.com/docs/cookbook/structured-output/) — Validate a provider response with a Standard Schema and pass the typed finding into a later <Agent />.

- [Define and grant a JavaScript Tool](https://agent-markup-language.com/docs/cookbook/tools/) — Create 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](https://agent-markup-language.com/docs/cookbook/changelog-maintainer/) | Credentialed + repository-backed                 | Script collector, Agent provider, schemas, and a document writer                    | Composable Agents around deterministic release work |
| [Code-review workflow](https://agent-markup-language.com/docs/cookbook/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](https://agent-markup-language.com/docs/cookbook/structured-output/)          | Deterministic                                    | Node, SDK, `zod`                                                                    | Typed findings and validation boundaries            |
| [Tools](https://agent-markup-language.com/docs/cookbook/tools/)                                  | Deterministic                                    | Node, SDK/testing, `zod`                                                            | Application-owned functions and capability scoping  |

## Add capabilities and resources

- [Test capabilities and resources](https://agent-markup-language.com/docs/cookbook/testing/) — Run a complete workflow with runtime-level testing providers, inspect normalized calls, and spy on resource lifecycle hooks.

- [Model Context Protocol capabilities](https://agent-markup-language.com/docs/cookbook/mcp/) — Learn MCP descriptor validation and Agent scoping. The included example URL is fixture metadata; this recipe makes no connection.

- [Combine Sandboxes and Workspaces](https://agent-markup-language.com/docs/cookbook/sandboxes-and-workspaces/) — Materialize files in a temporary local Workspace, narrow an execution Sandbox, and understand trusted-host boundaries.

- [Run AML in a Sandbox image](https://agent-markup-language.com/docs/cookbook/sandbox-image/) — Start AML's recommended image through Docker, run commands inside it, and pin or replace the image deliberately.

- [Choose between a Tool and MCP](https://agent-markup-language.com/docs/cookbook/tool-or-mcp/) — Compare ownership, transport, credentials, failure modes, and host-process security with complete examples of both.

| Recipe                                                               | Status                                        | Needs                                                                            | Best for                                                              |
| -------------------------------------------------------------------- | --------------------------------------------- | -------------------------------------------------------------------------------- | --------------------------------------------------------------------- |
| [Testing AML workflows](https://agent-markup-language.com/docs/cookbook/testing/)                     | Deterministic                                 | Node, SDK/testing, Vitest                                                        | Replacing runtime defaults and asserting capability/resource behavior |
| [MCP capabilities](https://agent-markup-language.com/docs/cookbook/mcp/)                              | Deterministic fixture                         | Node, SDK/testing; no MCP server or credentials                                  | Capability isolation without pretending to run an external server     |
| [Tool or MCP?](https://agent-markup-language.com/docs/cookbook/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](https://agent-markup-language.com/docs/cookbook/sandbox-image/)                       | Resource-backed                               | Node, SDK, Docker, and AML Agent Sandbox                                         | Understanding image defaults and overrides                            |
| [Sandboxes and Workspaces](https://agent-markup-language.com/docs/cookbook/sandboxes-and-workspaces/) | Deterministic + resource-backed               | Node, SDK/testing, writable temp directory                                       | Local file materialization and execution-scope composition            |
| [Generated diagnostics](https://agent-markup-language.com/docs/cookbook/generated-diagnostic/)        | Deterministic Agent + resource-backed         | Node, SDK/testing, Docker, and the selected interpreter image                    | Treating generated code as data before explicit execution             |

**Caution — Resource-backed is not the same as isolated**

[`localSandbox()`](https://agent-markup-language.com/docs/providers/sandboxes/local/) 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](https://agent-markup-language.com/docs/providers/).

## Compose and operate real jobs

- [Operate AML in a background job](https://agent-markup-language.com/docs/cookbook/production-job/) — Set explicit runtime budgets, propagate cancellation, and emit content-minimizing traces around a real OpenCode Agent provider.

- [Stop a CLI workflow safely](https://agent-markup-language.com/docs/cookbook/cli-process-safety/) — Interrupt a real process tree and follow CLI cancellation through Sandbox release to the conventional exit status.

- [Observe a live Agent session](https://agent-markup-language.com/docs/cookbook/observe-agent-activity/) — Build an ordered activity feed from Agent turn spans and unchanged ACP updates across two FollowUps.

- [Correlate application observability](https://agent-markup-language.com/docs/cookbook/application-observability/) — Time custom phases and retrieve run-keyed summaries across overlapping evaluations.

- [Compose Codex, Docker, and S3](https://agent-markup-language.com/docs/cookbook/codex-docker-s3/) — Follow one production skeleton across a credentialed Agent, disposable container, and durable revisioned Workspace.

- [Route typed data safely](https://agent-markup-language.com/docs/cookbook/structured-routing/) — Validate a model-shaped route, canonicalize it, enforce root containment, and only then construct the selected Workspace.

| Recipe                                                                 | Status                                     | Needs                                                                                     | Best for                                                             |
| ---------------------------------------------------------------------- | ------------------------------------------ | ----------------------------------------------------------------------------------------- | -------------------------------------------------------------------- |
| [Production job](https://agent-markup-language.com/docs/cookbook/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](https://agent-markup-language.com/docs/cookbook/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](https://agent-markup-language.com/docs/cookbook/observe-agent-activity/)               | Credentialed                               | OpenCode executable, model credentials, and an approved content-capturing terminal        | Understanding live ACP activity across Agent turns                   |
| [Application observability](https://agent-markup-language.com/docs/cookbook/application-observability/) | Deterministic                              | Node, SDK, and application request context                                                | Custom phase timing and concurrent run correlation                   |
| [Codex + Docker + S3](https://agent-markup-language.com/docs/cookbook/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](https://agent-markup-language.com/docs/cookbook/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](https://agent-markup-language.com/docs/cookbook/follow-up-editorial-passes/) 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](https://agent-markup-language.com/docs/examples/) page. The runner remains the source of truth; the docs recommend paths by learning goal instead of maintaining a second export inventory.