<Include />

<Include /> reads exactly one file when AML evaluates it and contributes either its current UTF-8 content when inlined or a bounded instruction telling the Agent where to read it.

import { Agent, Block, Include } from "@aml-jsx/sdk"

;<Agent>
  Review the proposed policy.
  <Block tag="review-policy">
    <Include src="./instructions/review-policy.md" maxBytes={16_384} />
  </Block>
</Agent>

By default AML renders a Markdown heading followed by the body:

## Contents of `./instructions/review-policy.md`

…file content…

Set title="Review policy" to replace the heading text or title={false} to emit only the body.

Props

Prop	Type	Default	Meaning
src	string	exclusive	Application-owned local file resolved from AmlRuntime.cwd.
path	string	exclusive	File in the nearest active filesystem: Sandbox guest first, otherwise Workspace materialization.
maxBytes	number	unlimited	Positive byte ceiling for prompt inlining.
title	string | false	derived path	Markdown heading text, or false to omit the heading.

Exactly one of src or path is required. <Include /> does not accept children, and included files must contain valid UTF-8.

Source modes

src is trusted application-file access. AML resolves it from the runtime cwd; an enclosing Workspace or Sandbox does not change that source. If the file exceeds maxBytes, <Include src> must be inside an Agent: AML copies the complete UTF-8 file into that Agent’s private staging area and authors a read instruction containing the concrete Agent-visible path.

path is workflow-file access. AML resolves it from the nearest lexical filesystem owner, preferring the live Sandbox guest over an enclosing Workspace materialization. It requires one of those scopes. If the file exceeds maxBytes inside a Sandbox, AML leaves the file in place and authors a path relative to the effective Agent cwd. Without a Sandbox, an oversized host-Workspace path must be inside an Agent; AML copies its UTF-8 content into that Agent’s private staging area and authors the concrete staged path. The default heading still names the authored path.

AML caches up to 32 inspected file revisions per runtime. The revision key includes the filesystem, path, byte size, and modification time, so freshness follows the modification-time resolution reported by the filesystem provider. maxBytes is evaluated independently for every authored Include: it decides whether that request inlines content or emits a read instruction. The cache separately retains size and line count for every revision and keeps UTF-8 content only through 10 MiB. A metadata-only entry is promoted when a later request needs inline content; a later smaller maxBytes still emits a read instruction even when that content is cached. AML validates and counts a read-write Sandbox file that exceeds maxBytes as a stream instead of retaining its complete body. Host files (src and oversized host-Workspace path) are read completely because staging needs their bytes; only their cached content is dropped above 10 MiB. A read-only Sandbox uses its provider’s complete-file API because some providers intentionally prohibit all process execution when they cannot enforce read-only access. Oversized output reports the authored path, size, and line count before the Agent-visible read instruction.

<Workspace id="review" provider={workspace}>
  <File path="reports/findings.md">Generated findings</File>
  <Agent provider={reviewer}>
    <Include path="reports/findings.md" maxBytes={8_192} />
    Check these findings against the implementation.
  </Agent>
</Workspace>

Oversized staging is ephemeral and released with the containing Agent. Use <File /> when the intent is to write or copy a file into a Workspace or Sandbox filesystem, and use <Skill /> when the Agent should discover a complete Agent Skills package progressively instead of receiving prompt content immediately.