AML primitives

AML has fourteen stable authoring primitives. Each exists because the runtime must own a distinct piece of evaluation, capability scope, resource lifecycle, or broadly shared serialization rule. Branching, finite iteration, retries, and data transformation remain ordinary TypeScript; <Parallel> is the explicit boundary for independent AML branches.

<Agent /><Agent provider={…} system="…">

Runs one provider-owned Agent session. AML first resolves its prompt children, <System /> content, capabilities, and child <Agent /> results — then hands one complete plan to the provider.

Read reference →

<Parallel /><Parallel>…</Parallel>

Evaluates independent AML branches concurrently, waits for all branch cleanup, and contributes successful text in authored order. Failures surface together as ParallelError.

Read reference →

<Block /><Block>…</Block>

Adds exact blank-line separation and optional kebab-cased XML-style section tags without creating a runtime, capability, or control-flow scope.

Read reference →

<System /><System>…</System>

Adds resolved content to the owning <Agent /> system prompt. Multiple <System /> blocks are joined in authored order — and a child <Agent /> can generate system content for its parent.

Read reference →

<Tool /><Tool use={…} />

Grants the owning <Agent /> one schema-validated JavaScript capability created with defineTool(). Grants are scoped — sibling <Agent /> components never see each other's tools.

Read reference →

<Include /><Include src="./prompt.md" maxBytes={…} />

Reads a live application file or nearest-filesystem path into prompt text, with an optional byte ceiling and Agent-visible read instruction for larger content.

Read reference →

<Skill /><Skill src="./skills/evidence-review" />

Stages and registers one complete local Agent Skills package for the owning session, using native provider discovery or metadata-only fallback.

Read reference →

<File /><File path="handoff/plan.md">…</File>

Writes resolved child text or a local UTF-8 source through the nearest active filesystem without duplicating it into the surrounding prompt.

Read reference →

<Mcp /><Mcp use={…} />

Grants the owning <Agent /> an MCP server — provider-native by name, or an explicit server created with defineMcpServer(). Scope and lifecycle stay bound to that Agent session.

Read reference →

<FollowUp /><FollowUp>…</FollowUp>

Adds a later turn to the same provider-owned session. <FollowUp /> components are flat, ordered, and resolved before the session starts — the model keeps its own context between turns.

Read reference →

<Sandbox /><Sandbox access="read-only" root="…">

Acquires an ephemeral execution environment and scopes a narrowed filesystem policy to descendant <Agent /> components. Nested <Sandbox /> components narrow further while sharing the outer lease.

Read reference →

<Script /><Script cwd="…" command="…" /> | <Script shell="sh">

Runs an argument vector or resolved sh, bash, or node source on the trusted host or through the active <Sandbox /> runtime. Relative cwd resolves from the host runtime cwd or active Sandbox root.

Read reference →

<Workspace /><Workspace id="…" load save={…}>

Loads one durable filesystem snapshot, supplies its cwd to descendant <Sandbox /> components, and optionally saves a selected, .gitignore-aware revision after execution.

Read reference →

<> … </><>…</>

Groups AML values without adding prompt text or another runtime boundary — the plain JSX fragment, useful for composing capability bundles.

Read reference →

Choose by responsibility

Responsibility	Start with	Add when needed
Run a provider session	<Agent />	<System />, <Tool />, <Mcp />, <Skill />, <FollowUp />
Run independent AML branches	<Parallel />	Function components or Fragments when one branch contains ordered steps
Structure prompt content	<Block />	<Include /> for live application or workflow files
Execute a command	<Script />	<Sandbox /> when it must run in a selected environment
Materialize or preserve files	<Workspace />	<File /> and, when commands are needed, <Sandbox />
Group authored values	Fragment <>…</>	Function components and ordinary TypeScript

Read the tree in two directions

Scope flows from wrappers to descendants: <Workspace /> supplies a materialized directory, <Sandbox /> supplies execution authority, and <Agent /> scopes <Tool />, <Mcp />, <Skill />, <System />, and <FollowUp />. Results flow toward consumers: child values and <Include /> content resolve before <Agent />, <File />, <Script />, or another boundary that consumes them. <Block /> changes only exact text separation and optional model-facing section tags; it creates no scope.

Workspace scope  ──down──▶  Sandbox scope  ──down──▶  Agent capabilities
child result     ◀──up────  resolved input  ◀──up────  provider result

See The AML mental model for the complete evaluation model and AST and evaluation for node construction and placement rules.

Shared authoring rules

• Import primitives from @aml-jsx/sdk; do not import sdk/src/** implementation paths.
• Configure TypeScript with "jsx": "react-jsx" and "jsxImportSource": "@aml-jsx/sdk".
• Treat JSX indentation as authored text. AML concatenates text without inserting separators.
• Use provider props to override one boundary; otherwise the matching AmlRuntime default is used.
• Placement errors reject with EvaluationError. AML does not silently move capabilities or acquire missing resources. Host-capable primitives document when the absence of a Sandbox selects trusted local execution.

Continue with Runtime and evaluation for limits and cancellation, Provider boundaries for extension contracts, or the Cookbook for complete workflows.