> ## Documentation Index > Fetch the complete documentation index at: https://docs.mutagent.io/llms.txt > Use this file to discover all available pages before exploring further. # Tools, skills and files > How to write a tool module, add Helix built-in tools, write a skill, package files, declare secrets, and check, run, pack and deploy the agent. **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](/platform/managed-agents/agent-md#the-complete-example) shows in full. To build that agent step by step, see the [Quickstart](/platform/managed-agents/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](#write-a-tool) | | Read files, run commands or edit files | `harness.tools.builtin` | [Built-in tools](#built-in-tools) | | Follow written instructions for a kind of task | `harness.skills` | [Write a skill](#write-a-skill) | | Read data that ships with the agent | `harness.files` | [Files](#files) | | Use a token or other secret | `harness.bindings.secrets` and an Environment | [Secrets](#secrets) | ## The folder you start from ```text theme={null} 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: ```json package.json theme={null} { "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 ```typescript theme={null} 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 ```typescript theme={null} defineTool({ 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](#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 ```typescript theme={null} { 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: ```typescript theme={null} 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:`, 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. ```typescript tools/calculate-invoice.ts theme={null} 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({ 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; }; 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: ```json theme={null} { "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. ```typescript tools/list-products.ts theme={null} import { readFile } from "node:fs/promises"; import { join } from "node:path"; import { defineTool, Type } from "@mutagent/agents/tools"; export const listProducts = defineTool>({ 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; }; 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: ```text theme={null} widget: 1379 gadget: 2683 ``` ### Register the tools ```yaml agent.md theme={null} 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. ```yaml theme={null} 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](#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. ```text theme={null} skills/invoice-pricing/ ├── SKILL.md └── policy.json ``` ```markdown skills/invoice-pricing/SKILL.md theme={null} --- 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. ``` ```json skills/invoice-pricing/policy.json theme={null} { "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:`. | 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 1. When the agent starts, Helix loads each folder in `harness.skills`. 2. The model's instructions list each skill's name, description and the location of its `SKILL.md`. 3. When a task matches a description, the model reads `SKILL.md` with `read`, then the files it names. 4. A task that starts with `/skill:` 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 ```yaml agent.md theme={null} 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. ```yaml agent.md theme={null} harness: files: - assets/catalog.json ``` ```json assets/catalog.json theme={null} { "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, "")`: `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`. ```yaml agent.md theme={null} 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. | ```typescript theme={null} 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: 1. Store it in an Environment: `mutagent env set prod --secret PRICING_API_TOKEN=`. 2. Deploy and run the agent with `--env prod`. The Environment's variables and secrets are environment variables in the sandbox. 3. 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](/helix/cloud/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 ```bash theme={null} 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: ```text theme={null} 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 ```bash theme={null} 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: ```text theme={null} ┌─ ✓ 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](#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](/platform/managed-agents/agent-md). ## Pack and deploy ```bash theme={null} 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](/platform/managed-agents/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: ```text theme={null} [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](#common-refusals). From an empty folder to a deployed agent, a new revision and a rollback. Every field, every rule and the package format. This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.