# Agent Markup Language (AML)

> AML is a TypeScript framework for building AI agents and multi-agent applications with JSX. Compose existing coding-agent sessions, application tools, validated results, sandboxes, and persistent files as reusable components.

Website: https://agent-markup-language.com/
Documentation: https://agent-markup-language.com/docs/
Complete documentation: https://agent-markup-language.com/docs/llms.txt
Source: https://github.com/we-are-singular/aml
SDK package: https://www.npmjs.com/package/@aml-jsx/sdk
CLI package: https://www.npmjs.com/package/@aml-jsx/cli
CLI documentation: https://agent-markup-language.com/docs/cli/
Specification: https://github.com/we-are-singular/aml/blob/main/SPEC.md
License: MIT
Status: pre-stable and under active development.

## Reading the documentation

Use the focused page that matches the task before loading the complete corpus. Every documentation route has a source-Markdown alternative formed by adding `.md` to the route:

```sh
curl -fsSL https://agent-markup-language.com/docs/getting-started.md
curl -fsSL https://agent-markup-language.com/docs/cli.md
curl -fsSL https://agent-markup-language.com/docs/sandbox-images.md
curl -fsSL https://agent-markup-language.com/docs/providers/agents/codex.md
curl -fsSL https://agent-markup-language.com/docs/providers/agents/copilot.md
curl -fsSL https://agent-markup-language.com/docs/reference/primitives/agent.md
```

Use https://agent-markup-language.com/docs/llms.txt when a question spans multiple sections or when discovering the relevant page. The HTML and Markdown routes are generated from the same source. For an installed project, its `@aml-jsx/sdk` types remain authoritative when the current website documents a newer pre-stable version.

Use these primary documentation destinations:

- Learn: https://agent-markup-language.com/docs/
- CLI: https://agent-markup-language.com/docs/cli/
- Providers: https://agent-markup-language.com/docs/providers/
- Sandbox images: https://agent-markup-language.com/docs/sandbox-images/
- Cookbook: https://agent-markup-language.com/docs/cookbook/
- Reference: https://agent-markup-language.com/docs/reference/

## Project orientation

AML gives JSX a job unrelated to user interfaces: an AML tree describes executable dependencies between Agents, prompts, capabilities, Sandboxes, and durable Workspaces. `AmlRuntime` resolves that tree from the leaves upward, passes child results into parent prompts at their authored positions, and releases acquired resources in reverse order.

AML is not React, a visual workflow builder, or a replacement for TypeScript control flow. Conditions, functions,
promises, loops, and typed data collection remain ordinary TypeScript. JSX children resolve in authored order; sibling
JSX does not imply concurrency. `<Parallel>` explicitly marks independent text-producing branches, while
`Promise.all(evaluate(...))` remains available when component code needs individual results.

The library separates three provider responsibilities:

- Agent providers own model sessions, turns, native capabilities, and Agent Client Protocol translation.
- Sandbox providers own process execution, filesystem authority, cancellation, and ephemeral cleanup.
- Workspace providers own durable materialization, locking, revisions, restore, and save policy.

Those providers are independent choices around one authored AML tree.

## Install and configure

AML is ESM-only and currently requires Node.js 26 or newer.

```sh
npm install @aml-jsx/sdk
```

Configure TypeScript's automatic JSX runtime:

```json
{
  "compilerOptions": {
    "jsx": "react-jsx",
    "jsxImportSource": "@aml-jsx/sdk"
  }
}
```

Use `.tsx` for AML markup. React is not installed or involved.

## Credential-free first workflow

```tsx
import { Agent, AmlRuntime } from "@aml-jsx/sdk"
import { DeterministicAgentProvider } from "@aml-jsx/sdk/testing"

const provider = new DeterministicAgentProvider({
  name: "first-workflow",
  respond: request => ({ text: `Resolved: ${request.prompt}` }),
})

const result = await new AmlRuntime({ agentProvider: provider }).evaluate(
  <Agent>Explain what AML evaluates.</Agent>,
)
```

The deterministic testing provider requires no API key, network, or Agent executable. For a real provider, install and configure the compatible ACP executable in the host or Sandbox where AML will launch it.

## Run an exported workflow with the CLI

Install the experimental CLI beside the SDK when a trusted TSX workflow should run without application entry-point glue:

```sh
npm install @aml-jsx/sdk
npm install --save-dev @aml-jsx/cli
```

The workflow must export an AML tree. Put required providers directly on their components because the CLI creates an empty `AmlRuntime`:

```tsx
import { Agent } from "@aml-jsx/sdk"
import { DeterministicAgentProvider } from "@aml-jsx/sdk/testing"

const provider = new DeterministicAgentProvider({
  name: "cli-example",
  respond: request => ({ text: `Resolved: ${request.prompt}` }),
})

export default <Agent provider={provider}>Review README.md.</Agent>
```

```sh
npx aml run ./workflow.tsx
npx aml run ./workflow.tsx --entry namedExport --json --trace
```

The workflow file is positional; `--entry` selects an export inside it. Results go to stdout. Lifecycle events, errors, and metadata-only traces go to stderr. Do not create and evaluate another `AmlRuntime` inside the exported function; that bypasses CLI runtime ownership for the nested Agent work. Read https://agent-markup-language.com/docs/cli/ for environment precedence, export resolution, content-capture policy, and the trusted-code boundary.

## Agent and ACP observability

AML traces actual `agent.session`, ordered `agent.turn`, and `agent.cleanup` spans. A shared-ACP turn normally issues one `session/prompt` request; a final structured-output turn can issue one additional repair prompt when no valid result was submitted. A turn is not an underlying model API call. Every ACP notification is exposed as one `acp.session.update` with ACP-supplied `sessionId` and `sessionUpdate`; an initial Tool call also includes `toolName` when ACP supplies its optional programmatic name. The console tracer omits repetitive `agent_message_chunk`, `agent_thought_chunk`, and `tool_call_update` lines while custom trace sinks continue to receive those events.

Metadata-only tracing is the default. The AML SDK's `captureContent` sink option and the CLI's `--capture-content` flag can additionally expose prompts, Agent messages and thoughts emitted through ACP, unchanged serialized ACP updates, raw Tool data, plans, structured results, commands, and failure messages. The option belongs to AML, not ACP, and must be treated as a sensitive data-handling decision.

Process telemetry uses an opaque `execution.id` for local and remote providers. `kill_requested`, `kill_completed`, `exited`, and `wait_failed` are distinct facts; AML never claims exit merely because termination was requested. See https://agent-markup-language.com/docs/observability/ for the complete event union, lifecycle tree, redaction rules, examples, and portable limitations.

## Core surface

- `<Agent>` runs one provider-owned session after its prompt, system content, capabilities, and child Agent results resolve.
- `<System>` contributes ordered system instructions to the nearest Agent.
- `<Block>` adds exact blank-line separation and optional kebab-cased XML-style section tags without creating a runtime scope or instruction priority.
- `<Tool>` grants a typed JavaScript Tool created with `defineTool()` to one Agent. Native harness tools are configured through the Agent provider and permissions.
- `<Parallel>` runs independent branches concurrently, waits for their cleanup, and concatenates successful text in authored order. Use Blocks for separators or component-local `Promise.all(evaluate(...))` for individual typed values.
- `<Mcp>` grants a named or explicitly configured MCP server.
- `<Skill>` stages a complete local Agent Skills package for native discovery or metadata-only fallback without inlining its body.
- `<FollowUp>` adds an ordered later turn to the same Agent session.
- `<Workspace>` materializes durable files and may publish revision-backed state.
- `<File>` writes authored children or a local UTF-8 source to the nearest active Workspace or Sandbox filesystem.
- `<Include>` reads UTF-8 content from a local source or the nearest active filesystem and applies an optional prompt-inline byte limit.
- `<Sandbox>` acquires ephemeral execution and scopes filesystem policy.
- `<Script>` executes a literal command or resolved script on the trusted host or through the active Sandbox, with an optional portable relative cwd.
- `AmlRuntime` owns complete root evaluation, limits, cancellation, events, tracing, and cleanup.
- Component-local `evaluate()` starts nested evaluation inside an active AML function component and can validate structured output.

`Loop` and scoped Context are public draft surfaces. Consult the current docs before depending on them.

## Built-in providers

Agent providers:

- `codexAgent()` for Codex through `codex-acp`.
- `copilotAgent()` for GitHub Copilot CLI's native `copilot --acp` server.
- `glmAgent()` for Z.ai Coding Plan models through `glm-acp-agent`.
- `opencodeAgent()` for OpenCode's ACP server.
- `piAgent()` for `pi-acp` and Pi.

Sandbox providers:

- `localSandbox()` for trusted host development; it is not an isolation boundary.
- `dockerSandbox()` for disposable container execution using AML's default image or an application override.
- `daytonaSandbox()` for disposable Daytona environments.
- `modalSandbox()` for disposable Modal Sandboxes.

Docker, Daytona, and Modal default to AML's stable full image. Stable single-Agent variants and the mutable, full GHCR `dev` channel are documented at https://agent-markup-language.com/docs/sandbox-images/.

Workspace providers:

- `localWorkspace()` for one existing durable host directory.
- `filesystemWorkspace()` for local archive or folder revisions.
- `s3Workspace()` for S3-compatible revision storage with conditional locking and publication.

The package also exports provider-authoring contracts and `@aml-jsx/sdk/testing` conformance helpers.

## Security and lifecycle boundaries

ACP is the session protocol, not the security boundary. A selected Sandbox must enforce the process, filesystem, network, identity, and resource policy the application requires. Agent permission mappings cannot grant or remove authority that the Sandbox does not enforce.

AML does not install Agent executables, build Docker images, provision remote credentials, or create S3 buckets. Credentials should come from the deployment environment or deliberate provider configuration, never from prompt text or Workspace files. Content capture in traces is off by default and should remain an explicit data-handling decision.

Revision-backed Workspaces become durable only after save and conditional publication complete. Healthy competing writers should produce `WorkspaceConflictError`; cancellation skips save. Every provider must release invocation-owned processes, temporary materialization, locks, and remote resources on success and failure.

## Coding-agent skill

Install the repository-backed AML authoring skill for compatible coding agents:

```sh
npx skills add we-are-singular/aml --skill aml-jsx
```

Add `-g` for a global installation. The skill guides AML authoring; an application still needs the SDK and its selected provider executables.

## Canonical references

- Getting started: https://agent-markup-language.com/docs/getting-started/
- Experimental CLI: https://agent-markup-language.com/docs/cli/
- Examples: https://agent-markup-language.com/docs/examples/
- Concepts and evaluation: https://agent-markup-language.com/docs/concepts/
- Cookbook: https://agent-markup-language.com/docs/cookbook/
- Provider catalog: https://agent-markup-language.com/docs/providers/
- Production guidance: https://agent-markup-language.com/docs/production/
- Runtime and provider reference: https://agent-markup-language.com/docs/reference/
- Complete LLM-readable docs: https://agent-markup-language.com/docs/llms.txt
- Executable examples: https://github.com/we-are-singular/aml/tree/main/examples/src
- AML authoring skill: https://github.com/we-are-singular/aml/tree/main/skills/aml-jsx