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

Run a coding-agent session with a prompt, instructions, and tools. AML resolves the Agent's children before opening the session, then returns the provider's response as text. A provider can be set on this Agent or inherited from the runtime.

Read reference →

<Parallel />

Run independent branches together and combine their results in the order you wrote them. The parent waits for every branch before continuing. The runtime's concurrency limit still applies, and failed branches are reported together after cleanup.

Read reference →

<Include />

Read a file into an Agent's prompt. Use src for an application file, resolved from the runtime's working directory, or path for a file in the active Sandbox or Workspace. maxBytes bounds how much content AML includes directly.

Read reference →

<Skill />

Give an Agent a local Agent Skills package, including its SKILL.md and supporting files. AML stages the package for that session and registers it through the provider. The agent can discover and read the skill as needed; its full instructions are not inserted into every prompt.

Read reference →

<Sandbox />

Choose the execution environment for the agents inside it, such as Docker or a remote container. Set access and root to limit their filesystem permissions. Nested Sandboxes reuse the outer environment and can narrow its permissions further.

Read reference →

<Workspace />

Keep files between runs under a stable workspace ID. The provider loads the files before evaluating the children; save publishes the changes afterward. Select local files, filesystem revisions, or S3-compatible storage according to how the application should persist its work.

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.