# Reference

A concise map of AML's runtime options, workflow boundaries, and provider contracts.
Canonical: https://agent-markup-language.com/docs/reference/
Documentation index: https://agent-markup-language.com/docs/
Complete documentation: https://agent-markup-language.com/docs/llms.txt

Reference is for decisions and stable boundaries. It explains what AML owns, what a provider owns, and which option or provider guide to choose. It is intentionally not a generated API catalogue: the published package declarations remain the exact TypeScript contract, while the guides under [Providers](https://agent-markup-language.com/docs/providers/) explain configuration and vendor behavior.

AML publishes the SDK and CLI independently, so each package keeps its own version history.

- [SDK changelog](https://agent-markup-language.com/docs/reference/changelog/sdk/) — Runtime, primitives, providers, Sandboxes, and Workspaces.

- [CLI changelog](https://agent-markup-language.com/docs/reference/changelog/cli/) — Direct TypeScript and TSX workflow execution through the aml command.

## Start with the question

| If you need to…                                                            | Start here                                                |
| -------------------------------------------------------------------------- | --------------------------------------------------------- |
| Understand an authored component, its props, placement, or result          | [Primitives](https://agent-markup-language.com/docs/reference/primitives/)                 |
| Configure evaluation limits, defaults, cancellation, or structured results | [Runtime and evaluation](https://agent-markup-language.com/docs/reference/runtime/)        |
| Define a portable stdio or HTTP MCP server                                 | [`defineMcpServer()`](https://agent-markup-language.com/docs/reference/mcp-server/)        |
| Test workflows or provider contracts without live infrastructure           | [Testing APIs](https://agent-markup-language.com/docs/reference/testing/)                  |
| Decide whether work belongs in an Agent, Sandbox, or Workspace             | [Provider contracts](https://agent-markup-language.com/docs/reference/providers/)          |
| Implement a custom Agent, Sandbox, or Workspace adapter                    | [Provider authoring](https://agent-markup-language.com/docs/reference/provider-authoring/) |
| Choose a built-in Agent, Sandbox, or Workspace                             | [Provider catalog](https://agent-markup-language.com/docs/providers/)                      |
| Learn how a provider behaves in production                                 | The relevant [provider guide](https://agent-markup-language.com/docs/providers/)           |
| Assemble a task from working examples                                      | [Cookbook](https://agent-markup-language.com/docs/cookbook/)                               |
| Understand what changed between published versions                         | [Changelog](https://agent-markup-language.com/docs/reference/changelog/)                   |

## AML's three boundaries

```text
<Workspace />  → durable state and materialization
<Sandbox />    → execution authority and environment
<Agent />      → model or harness session
```

These boundaries compose, but they are not interchangeable. A Workspace gives descendants a materialized directory; it does not execute commands. A Sandbox executes literal commands and processes; its security properties depend on the selected provider and deployment. An Agent owns a provider session; it should not be used as a substitute for storage or an enforcing execution boundary.

## Import the supported boundary

Application code imports runtime features from `@aml-jsx/sdk`. TypeScript selects the package's JSX runtime automatically when `jsxImportSource` is set to `@aml-jsx/sdk`; applications do not maintain those compiler imports by hand. [Deterministic fixtures and provider conformance helpers](https://agent-markup-language.com/docs/reference/testing/) are available from `@aml-jsx/sdk/testing` when a workflow needs a credential-free provider.

Paths under `sdk/src/**` are implementation details, not supported imports. For working compiler and execution configuration, use [Getting started](https://agent-markup-language.com/docs/getting-started/) and [Deployment](https://agent-markup-language.com/docs/production/deployment/) instead of copying an export inventory. For authored AML, use the hand-maintained [primitive reference](https://agent-markup-language.com/docs/reference/primitives/): it documents behavior and composition boundaries without turning internal types into a second API surface.

## Stability and source of truth

AML is pre-stable. This Reference describes the current SDK behavior and the decisions users need to make; it does not promise that every declaration will remain unchanged between releases. When the distinction matters, follow the provider guide and the linked source contract together.

- [Runtime source](https://github.com/we-are-singular/aml/blob/main/sdk/src/core/aml-runtime.ts)
- [Evaluation source](https://github.com/we-are-singular/aml/blob/main/sdk/src/core/evaluate.ts)
- [SDK public barrel](https://github.com/we-are-singular/aml/blob/main/sdk/src/core.ts)
- [Provider catalog](https://agent-markup-language.com/docs/providers/)