Triage an issue with Pi
Run pi-issue-triage with AML_ISSUE_FILE and Pi model credentials to classify issue text, propose labels, and draft a reply. It prints a proposal without posting to an issue tracker.
Examples
The examples package is the executable companion to these docs. Each example exports an AML tree; the shared runner creates an AmlRuntime, attaches the console tracer, and evaluates the selected workflow.
Run an example
Section titled “Run an example”Clone the repository and install its dependencies first. The examples use built package exports; npm run example builds its dependencies through the repository task runner.
git clone https://github.com/we-are-singular/aml.gitcd amlnpm ciFrom that repository root:
npm run example --npm run example -- reviewnpm run example -- structurednpm run example -- agent-teamThe first command prints the current filename-derived catalog. Treat that output and examples/run.ts as the source of truth; this page deliberately recommends paths instead of duplicating every filename.
The root npm run example command loads .env when present. Its task environment forwards AML_*, OPENCODE_API_KEY, OPENAI_API_KEY, and Z_AI_API_KEY; export or store the credentials required by the selected example without committing them. Existing shell variables take precedence over .env. Use absolute paths for input files and evidence directories because the runner executes inside the examples package.
If you installed with --ignore-scripts, deterministic examples can run while a native executable is still unprepared. Before live OpenCode examples, verify the repository installation with npm exec -- opencode --version; run npm rebuild opencode-ai if it reports that its postinstall script was skipped.
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:
npm run buildnode apps/cli/dist/index.js run ./examples/src/core/basic.tsxThe shared example runner remains useful for its catalog and common tracer. Use the CLI guide when your own workflow should expose a default or named export without a separate application entry point.
Choose by goal
Section titled “Choose by goal”Analyze a repository with GLM
Run glm-repository-analysis with AML_REPOSITORY_DIRECTORY, Z.ai credentials, and Docker to analyze a README and package manifest, verify quoted evidence, and generate an onboarding report.
Build a reusable agent team
Run agent-team for two release specialists followed by an editor. Named Blocks make the exact data passed between agents visible; the fixture requires no credentials.
Learn JSX evaluation
Run basic for deterministic bottom-up evaluation with no model, network, or filesystem effect. Run component-types to see AML.Component, optional children, required children, and async components together.
Run specialists in parallel
Run concurrency to see <Parallel> overlap independent Agents while preserving authored result order.
Validate typed results
Run structured to validate one deterministic <Agent /> result with a Standard Schema before using it later.
Call application Tools
Run programmatic-tool to execute a schema-validated Tool from component code without granting it to an Agent or model.
Build a useful review
Run review for materialized evidence, a real <Skill />, bounded <Include /> content, typed parallel reviewers, application validation, and synthesis. Live Agent providers are an explicit opt-in.
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.
Choose a Script directory
Run script to see a portable <Script /> cwd resolve from the active Sandbox root without contacting an external service.
Persist local work
Run workspace-local to write one named file under an OS temporary directory and reuse <Workspace />.
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.
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.
When an example needs infrastructure
Section titled “When an example needs infrastructure”The filename runner covers core, capabilities, resources, and integrations. Files under operations use their own entrypoints and are not names accepted by npm run example:
# Credential-free application tracing; this script owns its runtime.npx vite-node examples/src/operations/trace-summaries.tsx
# Credential-free local process lifecycle; interrupt with Ctrl+C as the recipe explains.npm run aml -- run ./examples/src/operations/cli-process-safety.tsx --traceThe live Agent activity recipe supplies the separate OpenCode command and credentials for observe-agent.tsx.
Run the maintained deterministic examples as tests with npm run test --workspace=@aml-jsx/examples after npm run build. Their snapshots verify resolved output; they do not establish live model quality or external-provider compatibility.
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.
For copyable, task-oriented walkthroughs with prerequisites and expected output, continue to the Cookbook.