# Examples

Choose a maintained AML example by learning goal, then let the repository runner show the current catalog.
Canonical: https://agent-markup-language.com/docs/examples/
Documentation index: https://agent-markup-language.com/docs/
Complete documentation: https://agent-markup-language.com/docs/llms.txt

The examples package is the executable companion to these docs. Each example exports an AML tree; the shared runner creates an [`AmlRuntime`](https://agent-markup-language.com/docs/reference/runtime/), attaches the console tracer, and evaluates the selected workflow.

**Tip — AML builds AML**

**Auto-author a changelog with AML**

AML's own changelogs are written by a real AML workflow. One repository-aware
[`<Agent />`](https://agent-markup-language.com/docs/reference/primitives/agent/) runs the authoritative commit collector, investigates the changes, and
returns a typed draft. A second Agent publishes that draft, then reviews and formats the result in a
[`<FollowUp />`](https://agent-markup-language.com/docs/reference/primitives/follow-up/).

[Explore the auto-authored changelog workflow →](https://agent-markup-language.com/docs/cookbook/changelog-maintainer/)

## Run an example

From the repository root:

```sh title="Terminal"
npm run example --
npm run example -- review
npm run example -- structured
```

The first command prints the current filename-derived catalog. Treat that output and [`examples/run.ts`](https://github.com/we-are-singular/aml/blob/main/examples/run.ts) as the source of truth; this page deliberately recommends paths instead of duplicating every filename.

Each maintained example also exports an AML tree, so the experimental CLI can run one source file directly. Build the repository CLI and try the credential-free basic example:

```sh title="Terminal"
npm run build --workspace=@aml-jsx/cli
node apps/cli/dist/index.js run ./examples/src/core/basic.tsx
```

The shared example runner remains useful for its catalog and common tracer. Use the [CLI guide](https://agent-markup-language.com/docs/cli/) when your own workflow should expose a default or named export without a separate application entry point.

## Choose by goal

**Learn JSX evaluation**

Run `basic` for deterministic bottom-up evaluation with no model, network, or filesystem effect.

[`core/basic.tsx`](https://github.com/we-are-singular/aml/blob/main/examples/src/core/basic.tsx)

[Read the mental model](https://agent-markup-language.com/docs/concepts/)

**Run specialists in parallel**

Run `concurrency` to see `<Parallel>` overlap independent Agents while preserving authored result order.

[`core/concurrency.tsx`](https://github.com/we-are-singular/aml/blob/main/examples/src/core/concurrency.tsx)

[Build the complete review workflow](https://agent-markup-language.com/docs/cookbook/code-review-workflow/)

**Validate typed results**

Run `structured` to validate one deterministic [`<Agent />`](https://agent-markup-language.com/docs/reference/primitives/agent/) result with a Standard Schema before using it later.

[`core/structured.tsx`](https://github.com/we-are-singular/aml/blob/main/examples/src/core/structured.tsx)

[Read the structured output recipe](https://agent-markup-language.com/docs/cookbook/structured-output/)

**Call application Tools**

Run `programmatic-tool` to execute a schema-validated Tool from component code without granting it to an Agent or model.

[`core/programmatic-tool.tsx`](https://github.com/we-are-singular/aml/blob/main/examples/src/core/programmatic-tool.tsx)

[Read the Tool reference](https://agent-markup-language.com/docs/reference/primitives/tool/#call-a-tool-from-application-code)

**Build a useful review**

Run `review` for materialized evidence, a real [`<Skill />`](https://agent-markup-language.com/docs/reference/primitives/skill/), bounded [`<Include />`](https://agent-markup-language.com/docs/reference/primitives/include/) content, typed parallel reviewers, application validation, and synthesis. Live Agent providers are an explicit opt-in.

[`integrations/review.tsx`](https://github.com/we-are-singular/aml/blob/main/examples/src/integrations/review.tsx)

[Build the complete review workflow](https://agent-markup-language.com/docs/cookbook/code-review-workflow/)

**Use disposable execution**

Run `docker` to cross a real container boundary. It uses the Docker daemon and may pull an image; its `<Agent />` is deterministic.

[`integrations/docker.tsx`](https://github.com/we-are-singular/aml/blob/main/examples/src/integrations/docker.tsx)

[Read the generated diagnostic recipe](https://agent-markup-language.com/docs/cookbook/generated-diagnostic/)

**Choose a Script directory**

Run `script` to see a portable [`<Script />`](https://agent-markup-language.com/docs/reference/primitives/script/) cwd resolve from the active Sandbox root without contacting an external service.

[`resources/script.tsx`](https://github.com/we-are-singular/aml/blob/main/examples/src/resources/script.tsx)

[Read the Script reference](https://agent-markup-language.com/docs/reference/primitives/script/)

**Persist local work**

Run `workspace-local` to write one named file under an OS temporary directory and reuse [`<Workspace />`](https://agent-markup-language.com/docs/reference/primitives/workspace/).

[`integrations/workspace-local.tsx`](https://github.com/we-are-singular/aml/blob/main/examples/src/integrations/workspace-local.tsx)

[Compose Sandboxes and Workspaces](https://agent-markup-language.com/docs/cookbook/sandboxes-and-workspaces/)

**Stop safely from the CLI**

Run `cli-process-safety.tsx` through `aml run`, interrupt it, and verify that cancellation reaps the tracked local process tree before exit.

[`operations/cli-process-safety.tsx`](https://github.com/we-are-singular/aml/blob/main/examples/src/operations/cli-process-safety.tsx)

[Build the process-safety walkthrough](https://agent-markup-language.com/docs/cookbook/cli-process-safety/)

**Watch a live Agent work**

Run `observe-agent.tsx` with OpenCode to turn Agent spans and captured ACP updates into an ordered activity feed across the initial turn and two FollowUps.

[`operations/observe-agent.tsx`](https://github.com/we-are-singular/aml/blob/main/examples/src/operations/observe-agent.tsx)

[Build the observability walkthrough](https://agent-markup-language.com/docs/cookbook/observe-agent-activity/)

## When an example needs infrastructure

The runner also discovers credentialed Agent examples and resource-backed Sandbox or Workspace examples. List the catalog first, then inspect the selected source before running it.

- **Deterministic** examples use fixtures from `@aml-jsx/sdk/testing`. They demonstrate AML contracts without claiming that a live model behaves identically.
- **Credentialed** examples start a real Agent adapter and can require an executable, model account, network access, and provider-specific environment variables.
- **Resource-backed** examples use a local directory, Docker daemon, or remote Sandbox. Their source owns the mutation and cleanup notes for that exact workflow.
- **Fixture** examples model a boundary without contacting the described service. The MCP example, for example, carries descriptor metadata but does not connect to its placeholder URL.

:::caution[Read effects before running]
A real Agent can inspect or mutate its effective working directory when its Sandbox and Workspace allow it. A prompt that says “read only” is not a filesystem security boundary.
:::

For copyable, task-oriented walkthroughs with prerequisites and expected output, continue to the [Cookbook](https://agent-markup-language.com/docs/cookbook/).