Tools, skills and files

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.

This page shows how to give a managed agent its own tools, skills and files. Every sample comes from the invoice-pricing agent that the agent.md reference shows in full. To build that agent step by step, see the Quickstart. A managed agent gets only what agent.md declares under harness::

You want the agent to	Declare it in	Section
Call your own TypeScript function	`harness.tools.modules`	Write a tool
Read files, run commands or edit files	`harness.tools.builtin`	Built-in tools
Follow written instructions for a kind of task	`harness.skills`	Write a skill
Read data that ships with the agent	`harness.files`	Files
Use a token or other secret	`harness.bindings.secrets` and an Environment	Secrets

The folder you start from

invoice/
├── agent.md                            frontmatter and instructions
├── package.json                        required when the agent has tool modules
├── tools/calculate-invoice.ts          a tool module
├── tools/list-products.ts              a second tool module
├── skills/invoice-pricing/SKILL.md     a skill
├── skills/invoice-pricing/policy.json  a file the skill uses
└── assets/catalog.json                 a file the tools read

package.json has no dependencies:

package.json

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

Only paths that agent.md declares are packaged. Other files in the folder are ignored.
Every path in agent.md is relative to the folder.
package.json must not list dependencies, devDependencies, optionalDependencies or peerDependencies. Third-party npm packages are not installed.

Write a tool

A tool is a TypeScript or JavaScript file that exports one tool definition. The compiler bundles it into the package and Helix registers it when the agent starts. You do not write a Helix extension.

The import

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

defineTool takes the tool definition and returns it unchanged. It types the definition.
Type builds the parameter schema. It is the TypeBox builder, so Type.Object, Type.String, Type.Integer, Type.Optional and the other TypeBox functions work.
You do not install @mutagent/agents. mutagent agent check, run, pack and deploy supply it when they bundle the tool. An editor without the package reports the import as unresolved; the commands still build the tool.

The definition

defineTool<Params>({
  name,         // the tool name the model calls
  label,        // a display label
  description,  // what the tool does; the model reads it to decide when to call the tool
  parameters,   // the input schema, built with Type
  async execute(toolCallId, params, signal, onUpdate, context) {
    return { content: [{ type: "text", text: "…" }], details: {} };
  },
});

Field	Type	Meaning
`name`	string	The tool name. It must equal the `name` you give the module in `harness.tools.modules`.
`label`	string	A display label.
`description`	string	Shown to the model with the tool.
`parameters`	TypeBox schema	The input the model must send. Use `Type.Object({})` for a tool with no input.
`execute`	async function	Runs the tool and returns its result.

execute receives five arguments:

Argument	Type	Meaning
`toolCallId`	string	The ID of this call.
`params`	`Params`	The model’s input. Helix has already checked it against `parameters`.
`signal`	`AbortSignal` or `undefined`	Aborted when the run is aborted. Pass it to long operations.
`onUpdate`	function or `undefined`	Call it with a partial result, in the same shape as the return value, to report progress.
`context`	object	The agent’s context. See the next table.

context holds:

Field	Value
`context.agent.contextVersion`	`1`.
`context.agent.artifactDigest`	The artifact digest of the package that runs.
`context.agent.revisionId`	The revision that runs on Helix Cloud. `undefined` in `mutagent agent run`.
`context.paths.assetRoot`	The folder that holds the packaged `harness.files`. See Files.
`context.paths.workspaceRoot`	The session’s working directory. On Helix Cloud, a new empty folder for each run. In `mutagent agent run`, the agent folder on your machine.
`context.bindings.secret(name)`	Returns the value of a declared secret binding. Throws when the name is not declared or has no value.
`context.bindings.optionalSecret(name)`	Returns the value of a binding declared with `required: false`, or `undefined`. Throws when the name is not declared or the binding is required.

What execute returns

{ content: [{ type: "text", text: string }, …], details?: unknown }

content is a list of text parts. The model reads them as the tool’s result.
details is optional. It is stored with the tool result in the session’s events, so you can read structured data there. Put anything the model must read into content.

How errors reach the agent

What happens	What the agent sees
`execute` throws an `Error`.	The tool result is the error’s message, marked as an error. The run continues and the model decides what to do next.
The model sends input that does not match `parameters`.	`execute` does not run. The tool result is the validation error, marked as an error.
The module throws while it loads, the export is not a tool, or its `name` differs from `agent.md`.	The agent does not start. `mutagent agent run` fails with `AGENT_REGISTRATION_MISSING`. A run on Helix Cloud is refused with 422.

The invoice tool throws for an SKU the catalog does not have:

if (unitCents === undefined) throw new Error(`Unknown product: ${params.sku}`);

With the task “Call calculate_invoice with sku sprocket …”, the tool result is Unknown product: sprocket, and the model reports that the SKU is not in the catalog.

What a tool module can import

Import	Allowed
`@mutagent/agents/tools`	Yes.
Node built-ins, written `node:<name>`, for example `node:fs/promises`	Yes.
Relative files inside the agent folder, with the extension written: `./util.ts`, `./rates.json`	Yes. The imported files are packaged with the tool.
A relative import without the extension, for example `./util`	No. `./util` does not find `util.ts`: `check` refuses it with `SOURCE_NOT_FOUND`.
A file outside the agent folder	No (`PATH_ESCAPE`).
Any npm package, for example `zod`	No (`DEPENDENCIES_UNSUPPORTED`).
`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`).

check reads the imports without running any tool code.

A tool with input

tools/calculate-invoice.ts takes four fields. additionalProperties: false refuses any other field.

tools/calculate-invoice.ts

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 };
  },
});

The model sends JSON that matches the schema:

{ "sku": "widget", "quantity": 3, "discountPercent": 7, "taxBasisPoints": 825 }

A tool with no input

tools/list-products.ts takes no input. Its schema is an empty object. It is a named export, so agent.md names the export.

tools/list-products.ts

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

export const listProducts = defineTool<Record<string, never>>({
  name: "list_products",
  label: "List products",
  description: "List every SKU in the packaged product catalog with its unit price in cents.",
  parameters: Type.Object({}, { 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 lines = Object.entries(catalog.products).map(([sku, cents]) => `${sku}: ${cents}`);
    return {
      content: [{ type: "text", text: lines.join("\n") }],
      details: { catalogVersion: catalog.version, products: catalog.products },
    };
  },
});

The model calls it with {}. The result is:

widget: 1379
gadget: 2683

Register the tools

agent.md

harness:
  tools:
    builtin: [read]
    modules:
      - path: tools/calculate-invoice.ts
        name: calculate_invoice
      - path: tools/list-products.ts
        export: listProducts
        name: list_products

Key	Required	Meaning
`path`	Yes	The module file: `.ts`, `.tsx`, `.js` or `.mjs`, inside the folder.
`export`	No	The export that holds the tool. The default is `default`.
`name`	Yes	The tool name: a letter, then up to 63 letters, digits, `_` or `-`.

What name does:

It is the name the model calls, and the name in the agent’s allowed tools.
It must equal the name inside defineTool. check does not compare them. When the agent starts, a different name stops the run.
It must be unique across modules (DUPLICATE_TOOL) and must not also be in harness.tools.builtin (TOOL_COLLISION).

Built-in tools

harness.tools.builtin lists the Helix built-in tools the agent gets. The agent gets no other built-in tool.

harness:
  tools:
    builtin: [read]

Each entry is a Helix built-in tool name. check does not validate the names.
These names start on a managed agent: read, bash, edit, write, grep, find and ls.
A name Helix does not start passes check and stops the run when the agent starts: the active tools differ from the declared ones. See The registration receipt.
A name in the top-level disallowed_tools is removed from the list.

When to use them:

Tool	Use it when
`read`	The agent has skills. It is required with `harness.skills` (`SKILL_REQUIRES_READ`). It also lets the model read files by path.
`grep`, `find`, `ls`	The model must search or list files in its working directory.
`bash`	The model must run shell commands.
`edit`, `write`	The model must change or create files in its working directory.

Grant the fewest tools the task needs. For work on your own data, write a tool module: it runs your code and returns only what you choose.

Write a skill

A skill is a folder with a SKILL.md file and the files it uses. The model reads the skill when the task matches its description.

skills/invoice-pricing/
├── SKILL.md
└── policy.json

skills/invoice-pricing/SKILL.md

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

skills/invoice-pricing/policy.json

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

SKILL.md frontmatter

Helix reads these fields:

Field	Required	Meaning
`description`	Yes	When to use the skill, up to 1024 characters. A skill without a description is not loaded. `check` does not report this.
`name`	No	The skill name: lowercase letters, digits and `-`, up to 64 characters. The default is the folder name.
`disable-model-invocation`	No	`true` leaves the skill out of the list the model sees. It then runs only when the task starts with `/skill:<name>`.

The body after the frontmatter is the skill’s instructions. Write them for the model: what to read, which tool to call, and what to report.

Files next to SKILL.md

Every file in the skill folder is packaged, except node_modules and .git folders.
The model reads them with read. Paths written in SKILL.md are relative to the skill folder.
A tool cannot find a skill’s files through context. Data a tool reads goes in harness.files.

How the agent uses a skill

When the agent starts, Helix loads each folder in harness.skills.
The model’s instructions list each skill’s name, description and the location of its SKILL.md.
When a task matches a description, the model reads SKILL.md with read, then the files it names.
A task that starts with /skill:<name> loads that skill’s instructions directly, including a skill with disable-model-invocation: true.

The model decides when to read a skill. To make a skill mandatory, say so in the body of agent.md, as the invoice agent does: “Every invoice request must follow the invoice-pricing skill.”

Register the skill

agent.md

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

Each path is a folder (SOURCE_NOT_DIRECTORY) that contains a SKILL.md (SKILL_MANIFEST).
read must be in harness.tools.builtin (SKILL_REQUIRES_READ).
A path that does not start with skills/ is placed under skills/ in the package.

Files

harness.files packages data the agent’s tools read.

agent.md

harness:
  files:
    - assets/catalog.json

assets/catalog.json

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

Each path is a file or a folder. A folder is packaged with every file in it, except node_modules and .git folders.
The files are placed under files/ in the package. context.paths.assetRoot is that folder, on your machine and on Helix Cloud.
A tool reads a file at join(context.paths.assetRoot, "<declared path>"): join(context.paths.assetRoot, "assets/catalog.json").
A declared path that already starts with files/ is not placed under files/ again. Read files/catalog.json at join(context.paths.assetRoot, "catalog.json").
Never read a packaged file through a path on your machine. The package runs in a temporary folder locally and in a sandbox on Helix Cloud.

Credential-like files, such as .env, .mutagentrc, *.pem or *.key, are refused (CREDENTIAL_PATH). Put secrets in an Environment.

Secrets

harness.bindings.secrets declares the secret names the agent’s tools read through context.bindings.

agent.md

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

Key	Required	Default	Meaning
`name`	Yes	—	A letter, then up to 63 letters, digits, `_` or `-`. Unique in the list (`DUPLICATE_BINDING`).
`required`	No	`true`	Whether the agent must not start without the value.

const token = context.bindings.optionalSecret("PRICING_API_TOKEN");
if (token === undefined) throw new Error("PRICING_API_TOKEN is not set");

What happens today:

Where	A binding with `required` unset or `true`	A binding with `required: false`
`mutagent agent check`	Valid.	Valid.
`mutagent agent run`	The run fails with `AGENT_REGISTRATION_REJECTED`: no value is supplied.	Runs. `optionalSecret` returns `undefined`.
`mutagent agent deploy`, `activate`	Refused with 422 `AGENT_REQUIRED_BINDINGS_UNSUPPORTED`, listing the names.	Deploys.
A run on Helix Cloud	—	Runs. `optionalSecret` returns `undefined`.

The platform does not yet add declared bindings to the sandbox by name. To give a tool a secret now:

Store it in an Environment: mutagent env set prod --secret PRICING_API_TOKEN=<token>.
Deploy and run the agent with --env prod. The Environment’s variables and secrets are environment variables in the sandbox.
Read it in the tool with process.env.PRICING_API_TOKEN.

In mutagent agent run, Helix gets the environment variables of your shell, so process.env reads your local values. See Environments.

The local loop

Check and run the agent on your machine before you deploy it. Neither needs a sign-in. Both need Bun 1.3.14, on PATH or named by MUTAGENT_BUN_BIN. run also needs Helix installed (mutagent install helix, or MUTAGENT_HELIX_BIN for another binary) and the API key of the LLM provider in model, in your local Helix login or your environment variables.

mutagent agent check

mutagent agent check invoice/agent.md

check compiles the folder and applies every rule. It sends no request, makes no model call and runs no tool code. A valid folder prints the digests, the package manifest and the launch settings:

success         true
status          valid
name            invoice-pricing
sourceDigest    sha256:510b…6832
artifactDigest  sha256:0633…48e25
archiveDigest   sha256:08d6…47a2
archiveSize     30654
manifest        {
  "formatVersion": 1,
  …

mutagent agent run

mutagent agent run invoice/agent.md "Price three widget units."

run compiles the folder, unpacks the package into a temporary folder, and runs the task with Helix on your machine. It creates nothing in the workspace. It prints a card, then the answer:

┌─ ✓ Agent run: completed ──────────────────────────────────┐
│                                                           │
│   status          completed                               │
│   artifactDigest  sha256:0633…48e25                       │
│   exitCode        0                                       │
│                                                           │
│ ─────────────────────────────────────────────────────────│
│                                                           │
│   Next                                                    │
│   → mutagent agent --help                                 │
│                                                           │
└────────────────────────────────────────────────────────────┘
Priced per the invoice-pricing policy (7% discount, 825 bps tax):

- **Total: 4164 cents** ($41.64)
- Catalog version: **catalog-v1**
- Receipt word: **cobalt-orchard**

Breakdown: subtotal 4137¢, discount −290¢, tax 317¢.

The answer is the model’s text, so its wording changes between runs. The numbers come from the tool.

The command exits with the run’s exit code: 0 when status is completed.
A failed run prints the card with status failed and no reason. Run it again with --json and read diagnostics. For example, a missing model key reads No API key found for zai.
--json also prints registration (the registration receipt) and messages, which hold every tool call and tool result.

Common refusals

Without --json, the CLI prints the message. With --json, it also prints code and diagnostics, which name the file.

Code	Command	Cause
`DEPENDENCIES_UNSUPPORTED`	`check`, `run`, `pack`, `deploy`	A tool imports an npm package, or `package.json` lists dependencies.
`SOURCE_NOT_FOUND`	`check`, `run`, `pack`, `deploy`	A declared path does not exist, or a relative import has no extension.
`SKILL_REQUIRES_READ`	`check`, `run`, `pack`, `deploy`	`harness.skills` is set and `read` is not in `harness.tools.builtin`.
`SKILL_MANIFEST`	`check`, `run`, `pack`, `deploy`	A skill folder has no `SKILL.md`.
`TOOL_COLLISION`, `DUPLICATE_TOOL`	`check`, `run`, `pack`, `deploy`	A module `name` is also a built-in name, or is declared twice.
`MODEL_FORMAT`	`check`, `run`, `pack`, `deploy`	`model` is not written `llm-provider/model`.
`TOOL_BUILD`	`check`, `run`, `pack`, `deploy`	A tool module does not bundle. The diagnostics hold the bundler messages.
`AGENT_REGISTRATION_MISSING`	`run`	The tool module did not register: it threw while loading, the export is not a tool, or its `name` differs from `agent.md`.
`AGENT_REGISTRATION_REJECTED`	`run`	The active tools differ from the declared tools, for example an unknown built-in name, or a required secret binding has no value.
`INVALID_ARGUMENTS` (exit code 1)	`run`	The argument is a slug. `agent run` takes a file; run a managed agent with `mutagent helix agent @slug`.
`BUN_NOT_FOUND`, `BUN_VERSION`	`check`, `run`, `pack`, `deploy`	Bun 1.3.14 is not on `PATH`. Install it, or set `MUTAGENT_BUN_BIN`.
`AGENT_LOCAL_START_FAILED`	`run`	Helix could not start. Run `mutagent install helix`, or set `MUTAGENT_HELIX_BIN`.

The full list of check rules is in the agent.md reference.

Pack and deploy

mutagent agent pack invoice/agent.md --output invoice.tgz
mutagent agent deploy invoice/agent.md --env prod

pack writes the package archive outside the folder. Nothing is uploaded. It prints a card with the artifact digest; --json prints the source, artifact and archive digests. You do not need pack to deploy.
deploy builds the same package, uploads it, and activates the revision in the slot. It checks the model, the Environment, the secret bindings and the sandbox provider. See Deployment.

The registration receipt

When the agent starts, the bundled tools register and print one registration receipt. On Helix Cloud it appears in the session’s output:

[mutagent:agent-package] {"type":"mutagent.agent.registration.v1","launchAbiVersion":1,"status":"verified","registeredTools":["calculate_invoice"],"activeTools":["calculate_invoice","read"],"expectedTools":["calculate_invoice","read"],"bindings":{"status":"verified","required":[],"optional":[],"available":[],"missing":[]},"artifactDigest":"sha256:0633…48e25","revisionId":"rev_…"}

Field	Meaning
`status`	`verified` when the active tools equal the expected tools and the bindings are verified.
`registeredTools`	The tool modules that registered.
`activeTools`	The tools Helix activated.
`expectedTools`	`harness.tools.builtin` plus every module `name`.
`bindings`	The declared required and optional bindings, the ones with a value, and the required ones without a value.
`artifactDigest`, `revisionId`	The package and revision that started.

On Helix Cloud, the platform waits up to 15 seconds for the receipt and checks that:

status is verified.
artifactDigest and revisionId are the revision’s.
activeTools and expectedTools equal harness.tools.builtin plus the module names.
registeredTools equals the module names.
The bindings are verified and match the declared required and optional names.

If a check fails, the run is refused with 422 AGENT_REGISTRATION_POLICY_MISMATCH, or with 422 AGENT_REGISTRATION_RECEIPT_TIMEOUT when no receipt arrives in 15 seconds. The sandbox the run started is stopped. mutagent agent run applies the same checks on your machine and fails with the codes in Common refusals.

Quickstart

From an empty folder to a deployed agent, a new revision and a rollback.

agent.md reference

Every field, every rule and the package format.

Overview

Sandbox

Managed agents

Setup

Tools, skills and files

The folder you start from

Write a tool

The import

The definition

What execute returns

How errors reach the agent

What a tool module can import

A tool with input

A tool with no input

Register the tools

Built-in tools

Write a skill

SKILL.md frontmatter

Files next to SKILL.md

How the agent uses a skill

Register the skill

Files

Secrets

The local loop

mutagent agent check

mutagent agent run

Common refusals

Pack and deploy

The registration receipt

Quickstart

agent.md reference

​The folder you start from

​Write a tool

​The import

​The definition

​What execute returns

​How errors reach the agent

​What a tool module can import

​A tool with input

​A tool with no input

​Register the tools

​Built-in tools

​Write a skill

​SKILL.md frontmatter

​Files next to SKILL.md

​How the agent uses a skill

​Register the skill

​Files

​Secrets

​The local loop

​mutagent agent check

​mutagent agent run

​Common refusals

​Pack and deploy

​The registration receipt

Quickstart

agent.md reference

The folder you start from

Write a tool

The import

The definition

What execute returns

How errors reach the agent

What a tool module can import

A tool with input

A tool with no input

Register the tools

Built-in tools

Write a skill

SKILL.md frontmatter

Files next to SKILL.md

How the agent uses a skill

Register the skill

Files

Secrets

The local loop

mutagent agent check

mutagent agent run

Common refusals

Pack and deploy

The registration receipt