Agents and versions
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.
On this page
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 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). |
memory | Optional, on request. Memory scopes the agent may use. |
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. |
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. A bundle that names a tool the runtime does not have is refused when its run starts.
Versions
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 channelsApplying 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 |
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 targetsThrough 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.
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: 90hexel 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 nameA 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
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 calledevalsfor 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 withharness:agent:promoteconfirms the promotion.
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 environmentA 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.