# AML primitives

Reference the fourteen stable AML authoring primitives, their placement rules, results, and composition boundaries.
Canonical: https://agent-markup-language.com/docs/reference/primitives/
Documentation index: https://agent-markup-language.com/docs/
Complete documentation: https://agent-markup-language.com/docs/llms.txt

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>`](https://agent-markup-language.com/docs/reference/primitives/parallel/) is the explicit boundary for independent AML branches.

## Choose by responsibility

| Responsibility                | Start with                                                | Add when needed                                                                                                                                                                                                                                             |
| ----------------------------- | --------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| Run a provider session        | [`<Agent />`](https://agent-markup-language.com/docs/reference/primitives/agent/)          | [`<System />`](https://agent-markup-language.com/docs/reference/primitives/system/), [`<Tool />`](https://agent-markup-language.com/docs/reference/primitives/tool/), [`<Mcp />`](https://agent-markup-language.com/docs/reference/primitives/mcp/), [`<Skill />`](https://agent-markup-language.com/docs/reference/primitives/skill/), [`<FollowUp />`](https://agent-markup-language.com/docs/reference/primitives/follow-up/) |
| Run independent AML branches  | [`<Parallel />`](https://agent-markup-language.com/docs/reference/primitives/parallel/)    | Function components or Fragments when one branch contains ordered steps                                                                                                                                                                                     |
| Structure prompt content      | [`<Block />`](https://agent-markup-language.com/docs/reference/primitives/block/)          | [`<Include />`](https://agent-markup-language.com/docs/reference/primitives/include/) for live application or workflow files                                                                                                                                                                 |
| Execute a command             | [`<Script />`](https://agent-markup-language.com/docs/reference/primitives/script/)        | [`<Sandbox />`](https://agent-markup-language.com/docs/reference/primitives/sandbox/) when it must run in a selected environment                                                                                                                                                             |
| Materialize or preserve files | [`<Workspace />`](https://agent-markup-language.com/docs/reference/primitives/workspace/)  | [`<File />`](https://agent-markup-language.com/docs/reference/primitives/file/) and, when commands are needed, [`<Sandbox />`](https://agent-markup-language.com/docs/reference/primitives/sandbox/)                                                                                                                          |
| Group authored values         | [Fragment `<>…</>`](https://agent-markup-language.com/docs/reference/primitives/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.

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

See [The AML mental model](https://agent-markup-language.com/docs/concepts/) for the complete evaluation model and [AST and evaluation](https://agent-markup-language.com/docs/ast/) 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`](https://agent-markup-language.com/docs/reference/runtime/) 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](https://agent-markup-language.com/docs/reference/runtime/) for limits and cancellation, [Provider boundaries](https://agent-markup-language.com/docs/reference/providers/) for extension contracts, or the [Cookbook](https://agent-markup-language.com/docs/cookbook/) for complete workflows.