Skip to content
Hexel StudioDocs

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.

FieldDescription
nameThe agent's name. It must match the name in the request path.
modelprovider/model, for example anthropic/claude-sonnet-5-5.
fallback_modelsOptional. Other models the agent may use; a fork may pick one of them.
instructionsThe agent's system instructions.
toolsSandbox and kernel tools the agent may use (below).
skillsOptional. Skills the agent may load.
output_schemaOptional. A JSON schema for a structured result; the agent then submits it with submit_result.
budgetsOptional. max_usd, max_steps, max_tokens, max_wall_clock_s: the agent's own limits. A task's budget can only narrow them.
knowledgeOptional, on request. Knowledge stores the agent may search (Knowledge and memory).
memoryOptional, on request. Memory scopes the agent may use.
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

ToolWhat it does
shellRuns a command in the task's sandbox. A command is cut after 280 seconds.
read_file, write_file, edit_fileRead, write and edit files in the sandbox's workspace.
list_files, search_filesList and search files in the sandbox's workspace.
export_fileExports a file as an artifact.
ask_userAsks a person a question. Every agent has it, whether or not the bundle lists it.
todo_writeKeeps the agent's plan.
schedule_wakeupLets the agent wait and resume later.
submit_resultSubmits 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

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:

FormRuns
auditorThe prod channel
auditor@canaryThe canary channel
auditor@v3Version 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.

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

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.