# AI agent workflow examples in TypeScript

Build AI workflows with runnable TypeScript recipes for Pi issue triage, GLM repository analysis, code review, structured output, tools, and background 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.

Type reusable components with [`AML.Component<Props>`](https://agent-markup-language.com/docs/ast/#type-application-components-explicitly). Import `AML` as a type from `@aml-jsx/sdk`; add `AML.PropsWithChildren<Props>` for optional nested content or `AML.PropsWithRequiredChildren<Props>` for required children.

**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

Start with [Getting started](https://agent-markup-language.com/docs/getting-started/#1-create-a-project) for SDK installation, the JSX runtime configuration, and a runner. Recipes build on that setup and focus on AML component design: what belongs in the tree, what application code must validate, and who owns capabilities, resources, and results. Each recipe lists only its additional dependencies and environment requirements.

`@aml-jsx/sdk/testing` is an import path included in the SDK, not a separately installable package. Install `zod` for schema examples and `vitest` as a development dependency for test examples. A code block labeled “Complete source” is intended to run with its stated prerequisites; smaller blocks illustrate changes to that source or require the surrounding application's values.

Recipes show an application entrypoint that constructs and evaluates an `AmlRuntime`; some separate that entrypoint from a reusable workflow file. The maintained examples also support the shared repository runner. 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.

Each recipe opens with its goal and, where useful, badges that tell you what to prepare:

- **No credentials needed** runs without a model account. It may still use local files or
  Docker, as the prerequisites explain.
- **Agent authentication required** needs a configured live Agent. Recipes that
  specifically require an API key say so.
- **Docker required** needs a running Docker daemon. Other resource badges name the required
  service or local files.

Comparison guides may have no badges. Check each recipe's prerequisites for the complete setup and its notes on file changes and isolation.

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

- [Triage issues with Pi and ACP](https://agent-markup-language.com/docs/cookbook/pi-issue-triage/) — Classify an issue, propose labels from a fixed policy, and draft a maintainer response with real Pi sessions.

- [Analyze a repository with GLM and ACP](https://agent-markup-language.com/docs/cookbook/glm-repository-analysis/) — Inspect bounded repository evidence in Docker, validate findings and quotes, and produce an onboarding report.

- [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                                            |
| ------------------------------------------------------------------ | ------------------------------------------------ | ----------------------------------------------------------------------------------- | --------------------------------------------------- |
| [Pi issue triage](https://agent-markup-language.com/docs/cookbook/pi-issue-triage/)                 | Credentialed; optional Docker                    | Pi, ACP and MCP adapters, model credentials, issue JSON                             | Label proposals and maintainer reply drafts         |
| [GLM repository analysis](https://agent-markup-language.com/docs/cookbook/glm-repository-analysis/) | Credentialed + Docker                            | GLM image, Z.ai credentials, README and package manifest                            | Evidence-backed onboarding reports                  |
| [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             |

The production-job recipe needs a configured live provider. Supply the executable, credentials, and Sandbox/Workspace providers required by your deployment before running it.

## 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, without repeating project setup.
5. **How it works** — why the components are composed this way, with links to the relevant component references, concepts, and provider or image contracts.
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.