> ## 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.
# Managed agents
> Write an agent as files, check and run it on your machine, deploy it to your workspace, and run it on Helix Cloud by name.
**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](/platform/managed-agents/quickstart) builds it file by file.
```text theme={null}
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](/platform/managed-agents/agent-md) for the fields and
[Tools and skills](/platform/managed-agents/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](/cli/installation), Bun 1.3.14 for the compiler, and, for `deploy` and the cloud
run, a [sign-in](/cli/commands/login) with a workspace selected. `run` also needs Helix and the model's
API key on your machine. The [Quickstart](/platform/managed-agents/quickstart#before-you-start) lists
each requirement with the command that checks it.
```bash theme={null}
mutagent agent check invoice/agent.md
# status valid · name invoice-pricing · artifactDigest sha256:
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
```
1. `check` compiles the folder and validates it. It sends no request and runs no tool code.
2. `run` runs the task with Helix on your machine. It creates nothing in the workspace.
3. `deploy` uploads the package as revision `v1` and makes it the active revision in `prod`.
4. `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](/cli/errors).
### check
```bash theme={null}
mutagent agent check invoice/agent.md
```
```text theme={null}
success true
status valid
name invoice-pricing
artifactDigest sha256:
```
### run
```bash theme={null}
mutagent agent run invoice/agent.md "Price three widget units."
```
```text theme={null}
┌─ ✓ 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 @`.
### pack
```bash theme={null}
mutagent agent pack invoice/agent.md --output invoice.tgz
```
```text theme={null}
┌─ ✓ Agent pack: packed ─────────────────┐
│ status packed │
│ artifactDigest sha256: │
└────────────────────────────────────────┘
```
`pack` writes the archive that `deploy` uploads, and uploads nothing. You do not need it to deploy.
### deploy
```bash theme={null}
mutagent agent deploy invoice/agent.md --env prod
```
```text theme={null}
┌─ ✓ 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
```bash theme={null}
mutagent agent list --json
```
```json theme={null}
{
"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
```bash theme={null}
mutagent agent inspect invoice-pricing --env prod --json
```
```json theme={null}
{
"agent": { "slug": "invoice-pricing", "model": "zai/glm-5.3", "status": "active", … },
"revisions": { "data": [ { "revision": 1, "artifactDigest": "sha256:", … } ] },
"deployment": { "environment": "prod", "activeRevision": 1, "enabled": true, … },
"sessions": [ { "reference": "hs1_", "environment": "prod", "revision": 1, … } ]
}
```
### activate
```bash theme={null}
mutagent agent activate invoice-pricing --revision v1 --env prod
```
```text theme={null}
┌─ ✓ 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
```bash theme={null}
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.
```text theme={null}
┌─ ✓ 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](/cli/commands/agent).
## 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 `@`. It keeps the revision it started with. |
An [Environment](/helix/cloud/environments) names a slot and loads its variables and secrets into
the sandbox, an [LLM provider](/platform/providers/overview) supplies the key for the model that
`agent.md` names, and a [sandbox provider](/helix/cloud/sandbox-providers) decides where each run
happens.
## Where next
Build the invoice-pricing agent from an empty folder, deploy it, change it and roll it back.
Every field of `agent.md` and the package it builds.
Write a tool module, add built-in tools, write a skill, and package files and secrets.
Revisions, slots and Environments: what deploy, activate, run, retire and archive check.
Every `mutagent agent` command and its flags.
Deploy and run managed agents from code.
This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.