<File />

<File /> writes exactly one application-owned source or resolved AML subtree into the nearest active filesystem and contributes no text to the surrounding AML result. Inside <Sandbox /> it writes the live guest; otherwise it writes the active <Workspace /> materialization.

<Workspace id="review-42" provider={workspace} save>
  <File path="handoff/plan.md">
    <Agent provider={planner}>Write the implementation plan.</Agent>
  </File>
  <Agent provider={reviewer}>Review handoff/plan.md.</Agent>
</Workspace>

The first Agent completes before <File /> writes its result, so the later sibling sees the complete file.

To copy an application file instead of resolving children, use src:

const runtime = new AmlRuntime({ cwd: import.meta.dirname })

await runtime.evaluate(
  <Sandbox provider={sandbox} access="read-write">
    <File src="./fixtures/policy.md" path=".agents/context/policy.md" />
  </Sandbox>
)

Props

Prop	Type	Default	Meaning
path	string	required	Portable relative destination beneath the nearest active filesystem root.
children	AmlRenderable	exclusive	AML content resolved to the UTF-8 file body.
src	string	exclusive	Application-owned UTF-8 file resolved from AmlRuntime.cwd.

Exactly one of children or src is required. Empty resolved child text is a valid empty file; a local source must be a regular file containing valid UTF-8.

Placement and write behavior

• Lexical placement selects the owner. A Sandbox guest wins over an enclosing Workspace replica; there are no routing props.
• Without an active Workspace or Sandbox, evaluation rejects.
• A read-only Sandbox still permits private Agent staging, but <File /> cannot write its live guest filesystem.
• Parent directories are created where the provider permits, non-file destinations are rejected, and built-in providers replace complete files rather than append.
• A Workspace write affects the current materialization. The Workspace save policy decides whether a revision is published.

Use <Include /> to read a live file into prompt text or emit a bounded Agent read instruction. See Sandbox and Workspace composition for the two resource boundaries.