agent.md reference

Early access. Cloud sessions and managed agent runs are not open to every account yet: we are letting accounts in gradually while we test. They run in a cloud sandbox operated by Mutagent, so there is nothing to host. A sandbox with nothing to do for 15 minutes stops; send the session a message and it wakes up, delivers your message and carries on in the same conversation.

A managed agent is a folder. Its entry file, agent.md, holds YAML frontmatter and a Markdown body. mutagent agent check validates the folder, mutagent agent pack builds the package from it, and mutagent agent deploy uploads that package as a revision. This page describes every field the compiler accepts and every rule it applies. For the platform model (agents, revisions, slots and runs), see Managed agents. For running an agent, see Helix Cloud: managed agents.

The folder

invoice/
├── agent.md                          the entry file: frontmatter and instructions
├── package.json                      required when the agent has tool modules
├── bun.lock                          optional; packaged when present
├── tools/calculate-invoice.ts        a tool module, declared in harness.tools.modules
├── skills/invoice-pricing/SKILL.md   a skill folder, declared in harness.skills
├── skills/invoice-pricing/policy.json
└── assets/catalog.json               a file, declared in harness.files

After deploy, the parts end up in three places:

Archive. The declared parts are built into one package archive: your source, the bundled tools, the skill folders and the files. Other files in the folder are not included.
Revision. The archive is stored as a revision, v1, v2 and so on, which never changes. Deploying the same content again reuses that revision.
Slot. The revision becomes the active revision of the slot named by --env. Each run in that Environment copies the active revision into its sandbox.
Only what agent.md declares is packaged: tool modules and the files they import, package.json, skill folders and the paths in harness.files. Other files in the folder are ignored.
You can pass the folder or its agent.md to check, pack, deploy and run.
The entry file must be named agent.md, in lowercase. A folder with two case variants of the name is refused.

agent.md

---
<frontmatter: the fields below>
---
<the Markdown body: the agent's standing instructions>

The file must begin with a --- line, and the frontmatter must end with a --- line.
The frontmatter is exactly one YAML document.
The body is the agent’s standing instructions for every task. It must not be empty. The task you pass when you run the agent is separate.
The body is not parsed for configuration. A --- line inside the body is part of the instructions.

YAML rules

Rule	Refusal code
Exactly one YAML document.	`YAML_DOCUMENT_COUNT`
The YAML parses, with no duplicate keys.	`YAML_PARSE`
No YAML aliases (`*name`).	`YAML_ALIAS`
No merge keys (`<<`).	`YAML_MERGE`
No custom tags (`!tag`).	`YAML_TAG`
Every mapping key is a string.	`YAML_KEY`
No key the schema does not define, at any level.	`AGENT_SCHEMA`
No `apiVersion`, `kind` or `metadata` key.	Refused before the schema check.
No `instructions` key. The body is the instructions.	`LEGACY_INSTRUCTIONS_FIELD`

Base fields

These top-level fields are a complete local agent definition. mutagent helix agent --file reads them. For a managed agent, name, description, model and thinking apply; tools and skills do not grant anything, and disallowed_tools only removes tools. A managed agent gets exactly what the harness block declares.

Field	Type	Required	Default	Validation
`name`	string	Yes	—	2 to 50 characters: a lowercase letter, then lowercase letters, digits or `-`.
`description`	string	No	—	1 to 1024 characters.
`model`	string	Yes	—	3 to 256 characters, written `llm-provider/model`, with no whitespace. The text before the first `/` is the LLM provider, and the rest is the model ID; neither may be empty.
`thinking`	string	No	—	1 to 32 characters. The value is not validated against Helix’s reasoning levels.
`tools`	string or list of strings	No	—	A comma-separated string of up to 4096 characters, or a list of names of 1 to 128 characters each.
`disallowed_tools`	string or list of strings	No	—	Same form as `tools`. `disallowedTools` is accepted with the same meaning; when both are set, `disallowed_tools` is used.
`skills`	string, list of strings, or boolean	No	—	Same form as `tools`, or `true` or `false`.

name

The agent’s slug in the workspace. deploy creates the agent with this slug, or adds a revision to the agent that already has it. You run the agent as @<name>.

name: invoice-pricing

description

One line on what the agent does. It is not part of the agent’s instructions.

description: Calculates invoices from a packaged pricing skill and catalog.

model

The model the agent always uses, as mutagent helix models lists it. The workspace default model is never used for a managed agent.

model: zai/glm-5.3

check refuses a value without an LLM provider and a model ID (MODEL_FORMAT).
deploy, activate and every run refuse a model that is not in the workspace model list (422), or whose LLM provider the workspace has not configured (428).
The API key comes from the workspace’s LLM provider when the sandbox starts. deploy never uploads a local key.

thinking

The reasoning level passed to Helix with the model.

thinking: low

tools, disallowed_tools, skills

The local brief. mutagent helix agent --file reads them.

tools: read, bash
disallowed_tools: [bash]

For a managed agent:

tools and skills grant nothing. Declare tools in harness.tools and skills in harness.skills.
disallowed_tools removes names from harness.tools.builtin. It cannot add a tool.

The harness block

harness: holds the deployment settings. It is optional. mutagent agent check, pack, deploy and run read it; mutagent helix agent --file ignores it. Unknown keys inside it are refused.

Key	Type	Required	Default	Validation
`harness.tools.builtin`	list of strings	No	none	Unique names of 1 to 64 characters.
`harness.tools.modules`	list of tool modules	No	none	See Tool modules.
`harness.skills`	list of paths	No	none	Unique paths. Each is a folder that contains a `SKILL.md`. Requires `read` in `harness.tools.builtin`.
`harness.files`	list of paths	No	none	Unique paths. Each is a file or a folder.
`harness.bindings.secrets`	list of secret bindings	No	none	See Secret bindings.
`harness.runtime.mode`	`interactive` or `headless`	No	`interactive`	One of the two values.
`harness.runtime.scaffold`	`standard`	No	`standard`	The only accepted value.

Every path is relative to the agent folder and follows the path rules.

harness.tools.builtin

The Helix built-in tools the agent gets. No other built-in tool is granted.

harness:
  tools:
    builtin: [read]

check does not validate the names against Helix’s tool list.
Names listed in disallowed_tools are removed.
When the agent starts, the tools Helix activates must equal the built-in tools plus the tool module names. If they differ, the run stops. See At run.

harness.tools.modules

Your own tools, written in TypeScript or JavaScript. A Python function is not a tool format, and agent.md has no field for MCP servers.

Key	Type	Required	Default	Validation
`path`	string	Yes	—	1 to 512 characters. A `.ts`, `.tsx`, `.js` or `.mjs` file in the folder.
`export`	string	No	`default`	1 to 128 characters. The export of the module that holds the tool.
`name`	string	Yes	—	1 to 64 characters: a letter, then letters, digits, `_` or `-`.

harness:
  tools:
    modules:
      - path: tools/calculate-invoice.ts
        name: calculate_invoice

name must be unique across modules (DUPLICATE_TOOL), and must not also be a built-in tool name (TOOL_COLLISION).
The export must be a tool written with defineTool, and its name must equal the declared name. This is checked when the agent starts, not by check.
The compiler bundles every module and the files it imports into one Helix extension. You do not write a Helix extension.
A folder with tool modules must contain package.json. See package.json.

What a tool module can import

Import	Allowed
`@mutagent/agents/tools`	Yes
Node built-ins, written `node:<name>`	Yes
Relative files inside the folder, with an explicit `.ts`, `.tsx`, `.js`, `.mjs` or `.json` extension	Yes. Write the extension: `./util` does not find `util.ts` and is refused (`SOURCE_NOT_FOUND`). An import of a file without one of these extensions is refused (`IMPORT_EXTENSION_REQUIRED` or `UNSUPPORTED_TOOL_INPUT`).
Any other package name	No (`DEPENDENCIES_UNSUPPORTED`). Third-party npm dependencies are not installed.
`http:`, `https:`, `data:`, `file:` or `bun:` URLs	No (`UNSUPPORTED_TOOL_IMPORT`).
`import()` or `require()` with anything but one string literal	No (`DYNAMIC_IMPORT`).
Imports with `type: "macro"`	No (`TOOL_MACRO`).

A module that does not parse is refused (TOOL_SYNTAX). check reads the imports without running any tool code.

Writing a tool

import { defineTool, Type } from "@mutagent/agents/tools";

export default defineTool<{ sku: string }>({
  name: "lookup_price",
  label: "Look up price",
  description: "Return the unit price of a SKU.",
  parameters: Type.Object({ sku: Type.String() }),
  async execute(toolCallId, params, signal, onUpdate, context) {
    return { content: [{ type: "text", text: params.sku }] };
  },
});

`defineTool` field	Meaning
`name`	The tool name. Must equal the `name` in `harness.tools.modules`.
`label`	A display label.
`description`	What the tool does, shown to the model.
`parameters`	The parameter schema, built with `Type`.
`execute`	Runs the tool. Returns `content` (a list of text parts) and optional `details`.

The last argument of execute, context, holds:

Field	Meaning
`context.paths.assetRoot`	The folder that holds the packaged `harness.files`. Read packaged files through it, never through a path on your machine.
`context.paths.workspaceRoot`	The session’s working directory.
`context.agent.artifactDigest`	The digest of the running package.
`context.agent.revisionId`	The revision that runs, when it runs as a managed agent.
`context.agent.contextVersion`	`1`.
`context.bindings.secret(name)`	Returns a declared secret binding’s value. Throws when the binding has no value.
`context.bindings.optionalSecret(name)`	Returns the value of a binding declared with `required: false`, or `undefined`. Throws for a required binding.

Reading a name that harness.bindings.secrets does not declare throws an error.

harness.skills

Skill folders to package. Each folder holds a SKILL.md and the files it uses.

harness:
  tools:
    builtin: [read]
  skills:
    - skills/invoice-pricing

Each path must be a folder (SOURCE_NOT_DIRECTORY) that contains a SKILL.md (SKILL_MANIFEST).
Every file in the folder is packaged, except node_modules and .git folders.
Skills require read in harness.tools.builtin (SKILL_REQUIRES_READ): the agent reads a skill’s files with it.
When the agent starts, Helix loads each skill from the package.
A skill is guidance the agent reads, not a tool it calls. Say in the body when the agent should read it, for example “For every invoice request, read the invoice-pricing skill first”.

harness.files

Other files to package, such as data your tools read.

harness:
  files:
    - assets/catalog.json

Each path is a file or a folder. A folder is packaged with every file in it, except node_modules and .git folders.
A tool reads them under context.paths.assetRoot, at the same relative path: join(context.paths.assetRoot, "assets/catalog.json").
A path that already starts with files/ is not placed under files/ again. A tool reads files/catalog.json at join(context.paths.assetRoot, "catalog.json").

harness.bindings.secrets

Secret names the agent’s tools read through context.bindings.

Key	Type	Required	Default	Validation
`name`	string	Yes	—	1 to 64 characters: a letter, then letters, digits, `_` or `-`. Unique in the list (`DUPLICATE_BINDING`).
`required`	boolean	No	`true`	—

harness:
  bindings:
    secrets:
      - name: GITHUB_TOKEN
        required: false

required defaults to true. deploy and activate refuse any required binding with 422 AGENT_REQUIRED_BINDINGS_UNSUPPORTED, listing the names. Set required: false on every binding.
Declared bindings are not added to the sandbox by name yet, so optionalSecret returns undefined. Put the value in the slot’s Environment instead; its variables and secrets are loaded into the sandbox on every run.

harness.runtime.mode

The run mode when the run command names none.

harness:
  runtime:
    mode: headless

Value	Run without `-p` or `--rpc`
`interactive` (default)	Opens a live session, as `--rpc` does.
`headless`	Refused with 422 before any sandbox starts: a headless run needs `-p "<task>"`.

-p "<task>" always runs headless, and --rpc always runs interactive.

harness.runtime.scaffold

The Helix scaffold the agent runs in. standard is the only accepted value and the default.

Path rules

These rules apply to every path in harness.tools.modules, harness.skills and harness.files, and to every file a tool module imports.

Rule	Refusal code
Relative to the agent folder, with no empty, `.` or `..` segment, and not absolute.	`PATH_ESCAPE`
The path exists.	`SOURCE_NOT_FOUND`
A file where a file is expected.	`SOURCE_NOT_FILE`
Not a symlink, and no symlink inside a packaged folder.	`SYMLINK_SOURCE`, `SYMLINK_ESCAPE`
Not a credential-like file: `.env`, `.env.*`, `.mutagentrc`, `id_rsa`, `id_ed25519`, `credentials`, `credentials.json`, or a name ending in `.pem`, `.key`, `.p12` or `.pfx`.	`CREDENTIAL_PATH`
No file contains `-----BEGIN PRIVATE KEY-----`.	`PRIVATE_KEY_CONTENT`
One path is not declared in two roles, for example as a tool and as a file.	`SOURCE_KIND_COLLISION`
Each path inside the package is at most 100 bytes.	`ARCHIVE_PATH_LENGTH`
A tool module ends in `.ts`, `.tsx`, `.js` or `.mjs`.	`TOOL_EXTENSION`

package.json

Required when harness.tools.modules is set.

{
  "name": "invoice-pricing-agent-source",
  "private": true,
  "type": "module"
}

It must be a JSON object (PACKAGE_JSON).
dependencies, devDependencies, optionalDependencies and peerDependencies must be absent or empty (DEPENDENCIES_UNSUPPORTED).
A bun.lock or bun.lockb in the folder is packaged with it.
Set "type": "module" for ES module tools, as the example does. The compiler does not check it.

mutagent agent check

mutagent agent check invoice/agent.md

check compiles the folder and validates it on your machine. It sends no request, needs no sign-in, makes no model call and runs no tool code. It needs Bun 1.3.14. It applies every rule on this page, builds the package in memory, and reports the result. With --json it prints status: valid, the name, the three digests, the archive size, the package manifest and the launch settings, or diagnostics naming each problem and its file. It exits 0 when the folder is valid and 1 on a refusal. Refusals about the entry file:

Condition	Refusal code
No `agent.md` in the folder, or the path does not exist.	`ENTRY_NOT_FOUND`
The file is named `Agent.md` or another case variant.	`ENTRY_CASE`
The file has another name.	`ENTRY_NOT_CANONICAL`
The folder holds more than one case variant of `agent.md`.	`AMBIGUOUS_ENTRY`
No frontmatter delimited by `---` lines.	`MARKDOWN_FRONTMATTER`
An empty body.	`MISSING_INSTRUCTIONS`

Tool modules are bundled during check. A bundling error is refused with TOOL_BUILD. A valid check shows that the folder compiles. It does not show that the model follows your instructions or skills. Run a task with mutagent agent run and read the answer and the tool calls before you deploy.

mutagent agent pack

mutagent agent pack invoice/agent.md --output invoice.tgz

pack builds the same package as check and writes it to --output. Nothing is uploaded.

--output must be outside the agent folder (AGENT_OUTPUT_IS_SOURCE). An existing file is replaced only with --force (AGENT_OUTPUT_EXISTS).
The archive is a gzip-compressed tar file. The same source, compiled with the same compiler and Bun versions, produces the same archive.
With --json it prints three digests, each written sha256: and 64 hex characters. Without --json, its card shows the artifact digest.

Digest	Covers
Source digest	The declared source files: their paths and contents.
Artifact digest	The package manifest: every packaged file with its size and digest, and the compiler and Bun versions.
Archive digest	The archive file itself.

deploy builds the package the same way; you do not need to run pack first.

What the package contains

Path in the package	What it holds
`manifest.json`	Every file with its size, digest and role, the source digest, the artifact digest and the build versions.
`launch.json`	The launch settings: the model, the allowed tools, the skill paths, the required and optional bindings, the mode and the scaffold.
`source/agent.md`	Your `agent.md`, unchanged.
`source/...`	Your tool modules, the files they import, `package.json` and the lock file.
`skills/...`	Your skill folders. A path that does not start with `skills/` is placed under `skills/`.
`files/...`	Your `harness.files`, under `files/` at their relative paths. A path that already starts with `files/` keeps that path.
`generated/agent.md`	The prompt Helix loads: the name and your instructions.
`generated/tools.mjs`, `generated/tools.mjs.map`	The bundled tool modules and their source map.

Deploy refuses an archive larger than 16 MiB, or one whose files total more than 64 MiB when extracted.

How the platform uses each field

At deploy and activate

Field	What the platform does
The package	Verifies the archive digest, the artifact digest and every file digest. Refuses an archive over the size limits.
`name`	Creates the agent with this slug, or adds the revision to the existing agent. Refused with 409 when an inline agent uses the slug.
`model`	Refuses a model outside the workspace model list (422), or of an LLM provider the workspace has not configured (428).
`harness.bindings.secrets`	Refuses any required binding (422 `AGENT_REQUIRED_BINDINGS_UNSUPPORTED`).
Sandbox providers	Refuses when no configured sandbox provider can receive a package (422).

Unchanged content reuses its existing revision.

At run

The platform checks the model again, and the slot’s Environment and the sandbox provider, before any sandbox starts.
It starts the sandbox with the workspace’s LLM provider keys and the Environment, copies the package in, and checks its digest.
It starts Helix with generated/agent.md as the prompt, model and thinking, the allowed tools (harness.tools.builtin plus the tool module names), each skill in harness.skills, and the bundled tools. harness.files are under context.paths.assetRoot.
When the session starts, the bundled tools register and report a registration receipt within 15 seconds. The receipt must show every declared tool module registered, the active tools equal to the allowed tools, the package’s artifact digest and revision, and the declared bindings available. Otherwise the run stops with 422 and its sandbox is stopped.
The task is sent (headless) or the session opens (interactive), and the run returns its receipt.

The complete example

This agent prices invoices. It reads a pricing policy from a skill and calls a tool that reads a product catalog.

invoice/
├── agent.md
├── package.json
├── tools/calculate-invoice.ts
├── skills/invoice-pricing/SKILL.md
├── skills/invoice-pricing/policy.json
└── assets/catalog.json

---
name: invoice-pricing
description: Calculates invoices from a packaged pricing skill and catalog.
model: zai/glm-5.3
thinking: low
harness:
  tools:
    builtin: [read]
    modules:
      - path: tools/calculate-invoice.ts
        name: calculate_invoice
  skills:
    - skills/invoice-pricing
  files:
    - assets/catalog.json
  runtime:
    mode: headless
---
You are the invoice pricing agent. Every invoice request must follow the invoice-pricing skill.
Read its SKILL.md and policy.json before calling calculate_invoice. Supply the calculator with
the policy values and the requested SKU and quantity. Never calculate the total yourself.
Report the tool's exact totalCents and catalogVersion, followed by the policy receiptWord.
Do not claim success if a skill file or tool is unavailable.

{
  "name": "invoice-pricing-agent-source",
  "private": true,
  "type": "module"
}

import { readFile } from "node:fs/promises";
import { join } from "node:path";
import { defineTool, Type } from "@mutagent/agents/tools";

interface InvoiceInput {
  sku: string;
  quantity: number;
  discountPercent: number;
  taxBasisPoints: number;
}

export default defineTool<InvoiceInput>({
  name: "calculate_invoice",
  label: "Calculate invoice",
  description: "Calculate exact invoice cents from the packaged product catalog and skill policy.",
  parameters: Type.Object({
    sku: Type.String(),
    quantity: Type.Integer({ minimum: 1, maximum: 100 }),
    discountPercent: Type.Integer({ minimum: 0, maximum: 100 }),
    taxBasisPoints: Type.Integer({ minimum: 0, maximum: 10_000 }),
  }, { additionalProperties: false }),
  async execute(_id, params, _signal, _onUpdate, context) {
    const catalogPath = join(context.paths.assetRoot, "assets/catalog.json");
    const catalog = JSON.parse(await readFile(catalogPath, "utf8")) as {
      version: string;
      products: Record<string, number>;
    };
    const unitCents = catalog.products[params.sku];
    if (unitCents === undefined) throw new Error(`Unknown product: ${params.sku}`);
    const subtotalCents = unitCents * params.quantity;
    const discountCents = Math.round(subtotalCents * params.discountPercent / 100);
    const netCents = subtotalCents - discountCents;
    const taxCents = Math.round(netCents * params.taxBasisPoints / 10_000);
    const result = {
      subtotalCents,
      discountCents,
      taxCents,
      totalCents: netCents + taxCents,
      catalogVersion: catalog.version,
      contextVersion: context.agent.contextVersion,
    };
    return { content: [{ type: "text", text: JSON.stringify(result) }], details: result };
  },
});

---
name: invoice-pricing
description: Required policy for invoice pricing requests; read its policy before using the calculator.
---

Read `policy.json` in this skill directory. Supply its `discountPercent` and `taxBasisPoints`
to `calculate_invoice` together with the requested SKU and quantity. The tool reads the catalog
from the packaged agent assets, so do not invent a unit price. Include the exact `receiptWord`
from this skill asset after the returned cents total and catalog version.

{
  "discountPercent": 7,
  "taxBasisPoints": 825,
  "receiptWord": "cobalt-orchard"
}

{
  "version": "catalog-v1",
  "products": {
    "widget": 1379,
    "gadget": 2683
  }
}

What each part does:

harness.tools.builtin: [read] grants read, which the skill needs.
harness.tools.modules registers calculate_invoice from the default export of tools/calculate-invoice.ts.
harness.skills packages skills/invoice-pricing with its SKILL.md and policy.json.
harness.files packages assets/catalog.json. The tool reads it at join(context.paths.assetRoot, "assets/catalog.json").
harness.runtime.mode: headless makes a run without -p or --rpc a refusal, so run it with a task.

mutagent agent check invoice/agent.md
mutagent agent deploy invoice/agent.md --env prod
mutagent helix agent @invoice-pricing --env prod -p "Price three widget units."

The task “Price three widget units.” returns totalCents: 4164 and catalogVersion: catalog-v1, and the answer ends with cobalt-orchard.

Deployment

Deploy, activate, run, retire and archive.

mutagent agent

Every mutagent agent command and its flags.

Overview

Sandbox

Managed agents

Setup

agent.md reference

The folder

agent.md

YAML rules

Base fields

name

description

model

thinking

tools, disallowed_tools, skills

The harness block

harness.tools.builtin

harness.tools.modules

What a tool module can import

Writing a tool

harness.skills

harness.files

harness.bindings.secrets

harness.runtime.mode

harness.runtime.scaffold

Path rules

package.json

mutagent agent check

mutagent agent pack

What the package contains

How the platform uses each field

At deploy and activate

At run

The complete example

Deployment

mutagent agent

​The folder

​agent.md

​YAML rules

​Base fields

​name

​description

​model

​thinking

​tools, disallowed_tools, skills

​The harness block

​harness.tools.builtin

​harness.tools.modules

​What a tool module can import

​Writing a tool

​harness.skills

​harness.files

​harness.bindings.secrets

​harness.runtime.mode

​harness.runtime.scaffold

​Path rules

​package.json

​mutagent agent check

​mutagent agent pack

​What the package contains

​How the platform uses each field

​At deploy and activate

​At run

​The complete example

Deployment

mutagent agent

The folder

agent.md

YAML rules

Base fields

name

description

model

thinking

tools, disallowed_tools, skills

The harness block

harness.tools.builtin

harness.tools.modules

What a tool module can import

Writing a tool

harness.skills

harness.files

harness.bindings.secrets

harness.runtime.mode

harness.runtime.scaffold

Path rules

package.json

mutagent agent check

mutagent agent pack

What the package contains

How the platform uses each field

At deploy and activate

At run

The complete example