Managed agents

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 an agent you write as files: an agent.md folder with its prompt, tools, skills and files. You check and run it on your machine, deploy it to your workspace, and run it on Helix Cloud by name.

The package

This is the invoice-pricing agent. It prices an invoice from a product catalog and a pricing policy. The Quickstart builds it file by file.

invoice/                        # the agent folder
├── agent.md                    # prompt, model, and what to package
├── package.json                # required with tool modules
├── tools/                      # tool modules
│   └── calculate-invoice.ts    # the calculate_invoice tool
├── skills/                     # skill folders
│   └── invoice-pricing/        # one skill
│       ├── SKILL.md            # the pricing rules the model reads
│       └── policy.json         # discount, tax and receipt word
└── assets/                     # packaged files
    └── catalog.json            # the product catalog the tool reads

agent.md declares every other part. Only what it declares is packaged. See agent.md for the fields and Tools and skills for writing each part.

The essentials

Four commands take the folder from your machine to Helix Cloud. prod is an Environment in your workspace; create it once with mutagent env set prod INVOICE_CURRENCY=USD. You need the CLI, Bun 1.3.14 for the compiler, and, for deploy and the cloud run, a sign-in with a workspace selected. run also needs Helix and the model’s API key on your machine. The Quickstart lists each requirement with the command that checks it.

mutagent agent check invoice/agent.md
# status  valid · name  invoice-pricing · artifactDigest  sha256:<digest>

mutagent agent run invoice/agent.md "Price three widget units."
# Agent run: completed, then the answer: Total 4164 cents, catalog-v1, cobalt-orchard

mutagent agent deploy invoice/agent.md --env prod
# Managed agent invoice-pricing v1 is active in Environment "prod".

mutagent helix agent @invoice-pricing --env prod -p "Price three widget units."
# Total: 4164 cents ($41.64), catalog catalog-v1, receipt word cobalt-orchard

check compiles the folder and validates it. It sends no request and runs no tool code.
run runs the task with Helix on your machine. It creates nothing in the workspace.
deploy uploads the package as revision v1 and makes it the active revision in prod.
mutagent helix agent @invoice-pricing starts a sandbox on Helix Cloud, copies the active revision into it, and runs the task.

Manage agents with mutagent agent

check, run and pack work on the folder on your machine. deploy, list, inspect, activate and retire work on the agents in your workspace. Add --json to any of them for the full result: one object on stdout, with success true exactly when the exit code is 0. Exit codes: 0 success, 1 failure (usage errors included), 2 key expired or invalid, 3 not signed in or no workspace. See Errors and exit codes.

check

mutagent agent check invoice/agent.md

success         true
status          valid
name            invoice-pricing
artifactDigest  sha256:<digest>

run

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

┌─ ✓ Agent run: completed ───────────────┐
│   status          completed            │
│   exitCode        0                    │
└────────────────────────────────────────┘
- **Total: 4164 cents** ($41.64)

run takes a folder or its agent.md. To run a deployed agent, use mutagent helix agent @<slug>.

pack

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

┌─ ✓ Agent pack: packed ─────────────────┐
│   status          packed               │
│   artifactDigest  sha256:<digest>      │
└────────────────────────────────────────┘

pack writes the archive that deploy uploads, and uploads nothing. You do not need it to deploy.

deploy

mutagent agent deploy invoice/agent.md --env prod

┌─ ✓ Agent deploy: active ───────────────┐
│   slug            invoice-pricing      │
│   revision        v1                   │
│   environment     prod                 │
│   activeRevision  v1                   │
└────────────────────────────────────────┘
Managed agent invoice-pricing v1 is active in Environment "prod".

Deploying changed content stores the next revision, v2, and makes it active. Deploying unchanged content reuses the existing revision.

list

mutagent agent list --json

{
  "success": true,
  "agents": [
    { "slug": "invoice-pricing", "model": "zai/glm-5.3", "status": "active", "slots": "prod=v1" }
  ],
  …
}

slots shows each Environment with its active revision, or retired.

inspect

mutagent agent inspect invoice-pricing --env prod --json

{
  "agent": { "slug": "invoice-pricing", "model": "zai/glm-5.3", "status": "active", … },
  "revisions": { "data": [ { "revision": 1, "artifactDigest": "sha256:<digest>", … } ] },
  "deployment": { "environment": "prod", "activeRevision": 1, "enabled": true, … },
  "sessions": [ { "reference": "hs1_<reference>", "environment": "prod", "revision": 1, … } ]
}

activate

mutagent agent activate invoice-pricing --revision v1 --env prod

┌─ ✓ Agent activate: active ─────────────┐
│   revision        v1                   │
│   activeRevision  v1                   │
└────────────────────────────────────────┘
Managed agent invoice-pricing v1 is active in Environment "prod".

activate makes an earlier or later revision active, which is how you roll back. It also enables a retired slot again.

retire

mutagent agent retire invoice-pricing --env prod --force

retire asks for --force (or -f) every time, --json included, so a slot is never retired by accident.

┌─ ✓ Agent retire: retired ──────────────┐
│   status          retired              │
│   enabled         false                │
└────────────────────────────────────────┘
Managed agent invoice-pricing is retired in Environment "prod"; running sessions finish, new runs are refused.

A new run in a retired slot is refused with MANAGED_AGENT_SLOT_RETIRED. Every flag, argument and refusal is in the mutagent agent reference.

What the platform keeps

Entity	What it is
Agent	One entry in the workspace’s agent list, named by its slug.
Revision	One package built from `agent.md`: `v1`, `v2`, and so on. It never changes.
Slot	The agent in one Environment, with one active revision. The slot with no Environment is the default slot.
Run	One session started from `@<slug>`. It keeps the revision it started with.

An Environment names a slot and loads its variables and secrets into the sandbox, an LLM provider supplies the key for the model that agent.md names, and a sandbox provider decides where each run happens.

Where next

Quickstart

Build the invoice-pricing agent from an empty folder, deploy it, change it and roll it back.

agent.md

Every field of agent.md and the package it builds.

Tools and skills

Write a tool module, add built-in tools, write a skill, and package files and secrets.

Deployment

Revisions, slots and Environments: what deploy, activate, run, retire and archive check.

mutagent agent

Every mutagent agent command and its flags.

TypeScript SDK

Deploy and run managed agents from code.

Overview

Sandbox

Setup

Managed agents

The package

The essentials

Manage agents with mutagent agent

check

run

pack

deploy

list

inspect

activate

retire

What the platform keeps

Where next

Quickstart

agent.md

Tools and skills

Deployment

mutagent agent

TypeScript SDK

​The package

​The essentials

​Manage agents with mutagent agent

​check

​run

​pack

​deploy

​list

​inspect

​activate

​retire

​What the platform keeps

​Where next

Quickstart

agent.md

Tools and skills

Deployment

mutagent agent

TypeScript SDK

The package

The essentials

Manage agents with mutagent agent

check

run

pack

deploy

list

inspect

activate

retire

What the platform keeps

Where next