FAQ
New to AML? Start here. These answers explain the essentials without assuming you already know AML’s components or provider terminology.
First things first
Section titled “First things first”What is AML?
Section titled “What is AML?”Agent Markup Language is a TypeScript library for building workflows with coding agents. It gives you a way to describe prompts, agents, tools, files, and execution environments as one readable tree, then run that tree from your application.
Start with the AML mental model for a visual explanation or getting started to run a small example.
Is AML a new programming language?
Section titled “Is AML a new programming language?”No. Despite the name, AML is ordinary TypeScript and JSX. There is no separate AML syntax, compiler, or graph configuration format to learn. You can use normal variables, functions, imports, loops, promises, and validation libraries around an AML workflow.
What can I build with it?
Section titled “What can I build with it?”AML is useful when an application needs to coordinate agent work: ask several agents to review the same change, research in parallel and combine the findings, let an agent work on files in a controlled environment, or route a result through validation before the next step.
Browse the examples for small patterns and the cookbook for complete workflows.
How is this different from calling an AI model directly?
Section titled “How is this different from calling an AI model directly?”A direct model call is often enough for one prompt and one response. AML is for the surrounding workflow: which agent receives which instructions and capabilities, where it can work, how several results fit together, and when resources should be cleaned up.
AML does not replace the coding agent or model. It composes and runs them as part of your application.
Do I need to know React?
Section titled “Do I need to know React?”No. AML uses JSX because nested tags make the shape and ownership of a workflow easy to see, but it does not render a user interface or use React. Basic TypeScript plus a little JSX syntax is enough.
The AST and evaluation guide explains what AML creates from JSX when you want the deeper version.
Trying AML
Section titled “Trying AML”What do I need to try it?
Section titled “What do I need to try it?”You need Node.js 26 or newer, an ESM project, and a runner that understands TypeScript and TSX. The first tutorial uses a deterministic test provider, so you do not need an API key, coding-agent executable, Docker daemon, or remote account.
Follow getting started for both the application-owned runtime and experimental CLI paths.
Do I need to write an application entry point to run a workflow?
Section titled “Do I need to write an application entry point to run a workflow?”No. An application can construct AmlRuntime when it needs complete control over defaults, limits, events, and process lifecycle. For local automation and standalone trusted workflow files, install @aml-jsx/cli, export the AML tree, and run npx aml run ./workflow.tsx.
The CLI guide documents export selection, environment files, JSON output, tracing, and why a CLI workflow should not construct a second nested runtime.
Does AML include an AI model or an account?
Section titled “Does AML include an AI model or an account?”No. AML does not sell model access or proxy credentials through an AML service. For live work, it connects to a coding-agent provider that you install and authenticate in the environment where AML runs.
For learning and repeatable examples, @aml-jsx/sdk/testing includes deterministic providers that do not call a model.
Which coding agents can I use?
Section titled “Which coding agents can I use?”AML includes adapters for Codex, GitHub Copilot, GLM, OpenCode, and Pi. An adapter connects AML to an existing installation; it does not install the agent or create its account for you.
The coding-agent guide compares setup and capabilities. You can also implement AML’s provider contract for another agent harness.
What do <Agent /> and the other angle-bracket names mean?
Section titled “What do <Agent /> and the other angle-bracket names mean?”They are AML components. Each component adds one piece of the workflow. For example, <Agent /> describes one coding-agent session, <Tool /> grants a function to an agent, and <Sandbox /> chooses where controlled work can run.
They are TypeScript values rather than UI elements. The component reference lists each public component and links to focused examples.
During evaluation, function component bodies run as AML descends into the tree and resolved values flow upward. Component bodies descend; results ascend explains when to return AML for natural composition and when to await evaluate(...) to collect a nested result before continuing.
When does the work actually start?
Section titled “When does the work actually start?”Creating JSX only builds a description of the workflow. No agent starts until your application asks AML to evaluate that value with runtime.evaluate(tree), or the CLI evaluates an exported tree with aml run. This makes it possible to construct and inspect a workflow before it performs outside work.
The runtime guide covers application-owned evaluation, limits, cancellation, and cleanup; the CLI guide covers standalone workflow files.
Agents, commands, and files
Section titled “Agents, commands, and files”Can one workflow use more than one coding agent?
Section titled “Can one workflow use more than one coding agent?”Yes. One agent’s result can become another agent’s input, and independent text-producing branches can run concurrently
inside <Parallel>. Use ordinary Promise.all(evaluate(...)) when component
code needs the individual results. Each <Agent /> remains a separate session with
its own explicitly granted instructions and capabilities.
See the code-review workflow for both parallel review and a final synthesis step.
Where will an agent run commands?
Section titled “Where will an agent run commands?”That depends on the provider and the environment you place around it. A local setup can use your machine directly. A <Sandbox /> can instead give the work a managed directory and process lifecycle through Docker, Daytona, Modal, or another sandbox provider.
Start with the sandbox guide before choosing an execution environment.
Can an agent change files on my computer?
Section titled “Can an agent change files on my computer?”Only if you give it access to those files. A local agent or localSandbox() can operate on the host and should be treated as trusted code. A remote or container sandbox limits the working environment according to that provider’s real isolation boundary.
Use <Workspace /> when files need to be materialized, revisioned, and saved deliberately. Sandboxes and Workspaces explains how execution and durable files fit together.
Does a sandbox make agent-written code completely safe?
Section titled “Does a sandbox make agent-written code completely safe?”No. A sandbox is one boundary, not a complete security policy. You still control credentials, network access, mounted files, images, resource limits, and which tools the agent can call. localSandbox() is a convenience for trusted local work and provides no isolation from the host.
Review the selected sandbox provider and the security guide before running model-controlled code.
Connecting AML to an application
Section titled “Connecting AML to an application”Can an agent call my application’s functions or APIs?
Section titled “Can an agent call my application’s functions or APIs?”Yes. defineTool() returns a schema-validated callable owned by your application. Call it directly from an active component when application code chooses the operation, or pass it to <Tool use={tool} /> when one Agent should receive it as a model-callable capability. AML can also connect an Agent through <Mcp /> to a separately operated Model Context Protocol server.
The Tools guide starts with a local function. The Tool or MCP guide explains when an external server is worth the extra moving parts.
Can I get predictable JSON instead of a prose answer?
Section titled “Can I get predictable JSON instead of a prose answer?”Yes. Use <Agent schema={Result}> when a nested Agent’s validated result should continue through the AML tree as canonical JSON text. Use component-local evaluate(<Agent>...</Agent>, Result) when TypeScript needs the schema-inferred value for an application decision.
Both forms apply the structured contract only to the final authored turn, so ordered <FollowUp> prompts can run first. Built-in ACP providers send one explicit schema-bearing repair prompt if that final turn omits the result Tool.
Validation proves that the value has the expected shape; it does not prove that the model’s claims are true or authorized. See structured output for a complete example.
Am I locked into one coding agent?
Section titled “Am I locked into one coding agent?”Usually not. The workflow tree is provider-neutral, while provider configuration owns details such as model names, executable paths, credentials, and permissions. You can change the configured provider without rewriting the whole tree, but different agents do not have perfectly identical capabilities or behavior.
Check the compatibility guide before changing a production workflow.
Can I use AML in a production service?
Section titled “Can I use AML in a production service?”Yes, when the surrounding service owns the operational concerns that AML deliberately leaves explicit: finite limits, cancellation, credentials, sandbox policy, durable storage, logs, and retry or idempotency behavior. AML manages the evaluation tree and its resource lifecycle; it is not itself a scheduler, secret store, or universal security boundary.
Continue with production readiness and the production job recipe.