AI agent workflow examples in TypeScript

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.

Type reusable components with AML.Component<Props>. Import AML as a type from @aml-jsx/sdk; add AML.PropsWithChildren<Props> for optional nested content or AML.PropsWithRequiredChildren<Props> for required children.

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

Start with Getting started 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 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 ACPClassify an issue, propose labels from a fixed policy, and draft a maintainer response with real Pi sessions.

Analyze a repository with GLM and ACPInspect bounded repository evidence in Docker, validate findings and quotes, and produce an onboarding report.

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
Pi issue triage	Credentialed; optional Docker	Pi, ACP and MCP adapters, model credentials, issue JSON	Label proposals and maintainer reply drafts
GLM repository analysis	Credentialed + Docker	GLM image, Z.ai credentials, README and package manifest	Evidence-backed onboarding reports
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

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 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 page. The runner remains the source of truth; the docs recommend paths by learning goal instead of maintaining a second export inventory.