---
title: Agents and versions
description: Define an agent as a spec bundle, apply it as an immutable version,
  route channels such as prod and canary, roll back, and manage it all from
  files.
url: https://hexelstudio.com/docs/harness/agents
---

An agent is defined by a **spec bundle**: its model, instructions, tools, skills and budgets. Each apply of a changed bundle makes a new **version**. Versions never change. **Channels** such as `prod` and `canary` point at versions, so you choose which version new tasks run without editing the agent.

Agents belong to an environment. Each agent also has an identity in the Agent Registry; a suspended or retired registry agent cannot run.

## The spec bundle

A bundle is YAML or JSON, at most 512 KiB.

| Field | Description |
| --- | --- |
| `name` | The agent's name. It must match the name in the request path. |
| `model` | `provider/model`, for example `anthropic/claude-sonnet-5-5`. |
| `fallback_models` | Optional. Other models the agent may use; a [fork](https://hexelstudio.com/docs/harness/fork-and-replay) may pick one of them. |
| `instructions` | The agent's system instructions. |
| `tools` | Sandbox and kernel tools the agent may use (below). |
| `skills` | Optional. Skills the agent may load. |
| `output_schema` | Optional. A JSON schema for a structured result; the agent then submits it with `submit_result`. |
| `budgets` | Optional. `max_usd`, `max_steps`, `max_tokens`, `max_wall_clock_s`: the agent's own limits. A task's budget can only narrow them. |
| `knowledge` | Optional, on request. Knowledge stores the agent may search ([Knowledge and memory](https://hexelstudio.com/docs/harness/knowledge-and-memory)). |
| `memory` | Optional, on request. Memory scopes the agent may use. |

```yaml auditor.yaml
name: auditor
model: anthropic/claude-sonnet-5-5
instructions: |
  Audit the repository you are given. Plan with todo_write, keep notes in files,
  ask the user when the goal is unclear, and export a report with export_file.
tools: [shell, read_file, list_files, search_files, write_file, export_file, todo_write]
budgets: {max_steps: 80, max_usd: 8}
```

### Tools

| Tool | What it does |
| --- | --- |
| `shell` | Runs a command in the task's sandbox. A command is cut after 280 seconds. |
| `read_file`, `write_file`, `edit_file` | Read, write and edit files in the sandbox's workspace. |
| `list_files`, `search_files` | List and search files in the sandbox's workspace. |
| `export_file` | Exports a file as an [artifact](https://hexelstudio.com/docs/harness/artifacts). |
| `ask_user` | Asks a person a question. Every agent has it, whether or not the bundle lists it. |
| `todo_write` | Keeps the agent's plan. |
| `schedule_wakeup` | Lets the agent wait and resume later. |
| `submit_result` | Submits the structured result. Added automatically with `output_schema`. |

File tools are confined to the run's workspace. Each sandbox tool is a Titan capability, decided by your policy: see [Approvals and autonomy](https://hexelstudio.com/docs/harness/approvals). A bundle that names a tool the runtime does not have is refused when its run starts.

## Versions

```bash
hexel harness agent apply auditor.yaml          # a new version, if the bundle changed
hexel harness agent versions auditor            # versions and their bundle digests
hexel harness agent get auditor@v3              # one version's bundle
hexel harness agent list                        # agents and their channels
```

Applying a bundle that is identical to the latest version makes no new version. Each version records its bundle's `sha256` digest, and every run records the exact version and digest it used.

## Channels

A channel points at one version, or splits new tasks between versions by weight. With `--weight` below 100, the version gets that share of the channel's new tasks and the channel's current main version keeps the rest. A task names its agent as:

| Form | Runs |
| --- | --- |
| `auditor` | The `prod` channel |
| `auditor@canary` | The `canary` channel |
| `auditor@v3` | Version 3 exactly |

```bash
hexel harness agent apply auditor.yaml --promote prod          # apply and point prod at it
hexel harness agent promote auditor 4 --channel prod --weight 10      # a 10% canary on prod
hexel harness agent rollback auditor --channel prod            # restore prod's previous targets
```

Through the API, `PUT /harness/agents/{name}/channels/{channel}` takes `{"targets": [{"version": 3, "weight": 90}, {"version": 4, "weight": 10}]}`, and `POST /harness/agents/{name}/versions?promote=prod` applies and promotes in one call. Pointing a channel needs `harness:agent:promote`, which Admins and Owners have by default.

## Manage agents from files

`hexel harness apply` makes an environment match a directory of YAML or JSON files: agents and their channels, triggers, webhooks and environment settings. It prints a plan (`+` create, `~` change, `-` delete, `=` unchanged) and makes only the changes, so applying the same directory twice changes nothing.

```yaml harness/auditor.yaml
kind: Agent
bundle_file: auditor.bundle.yaml
channels:
  prod: current                  # the version this bundle is
  canary: [{version: current, weight: 10}, {version: 3, weight: 90}]
---
kind: Trigger
name: nightly
agent: auditor@prod
goal: Audit the repositories
schedule: {cron: "0 2 * * *", timezone: Europe/London}
---
kind: Webhook
id: ops
url: https://ops.example.com/hooks/harness
event_types: ["task.*"]
---
kind: EnvironmentSettings
retention_days: 90
```

```bash
hexel harness apply -f harness/ --dry-run   # print the plan only
hexel harness apply -f harness/
hexel harness apply -f harness/ --prune     # also delete triggers and webhooks the files don't name
```

A document may name `environment: env_...`; `apply` then refuses to run in another environment. Agents and channels have no delete: `apply` never removes them.

## Promotions between environments

<Note>
On request. Promotions, promotion gates, version statistics, CI checks and agent templates are built but not turned on for every preview organization. Ask Hexel Studio if you need them.
</Note>

With promotions on, an environment administrator sets **promotion gates** on a target environment (for example production), and versions reach it only through a promotion from a named source environment:

- `{"type": "check", "name": "evals"}`: your CI posted a passing check called `evals` for the source version (`hexel harness agent check auditor 4 --name evals --status pass --url ...`).
- `{"type": "canary_success_rate", "min_success_rate": 0.95, "min_runs": 20}`: the version's success rate in the source environment.
- `{"type": "manual"}`: a second person with `harness:agent:promote` confirms the promotion.

```bash
hexel harness promote auditor 4 --from-env env_staging --to-channel prod
hexel harness agent stats auditor 4      # runs, success rate, mean cost in this environment
```

A promotion that passes its gates copies the bundle into the target environment as the agent's next version and points the channel at it. One that fails is refused with `409 gates_failed` and the gate results.
