# <Include />

Read a live file into authored prompt text, with an optional byte limit and Agent-visible fallback path.
Canonical: https://agent-markup-language.com/docs/reference/primitives/include/
Documentation index: https://agent-markup-language.com/docs/
Complete documentation: https://agent-markup-language.com/docs/llms.txt

`<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.

```tsx
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:

```md
## 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`](https://agent-markup-language.com/docs/reference/runtime/).         |
| `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.

```tsx
<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 />`](https://agent-markup-language.com/docs/reference/primitives/file/) when the intent is to write or copy a file into a Workspace or Sandbox filesystem, and use [`<Skill />`](https://agent-markup-language.com/docs/reference/primitives/skill/) when the Agent should discover a complete Agent Skills package progressively instead of receiving prompt content immediately.