Harness configuration and tuning

The harness is the program that runs the agent loop in the sandbox: OpenHands software-agent-sdk agent-server 1.49.6, started and driven by a small entrypoint, agent-run (agent-platform images/agent-harness/). The isolation around it is on Runtime; model routing and prices are on the routing and cost page. This page owns the configuration of a run and how to tune it.

Status on gcp-0, 2026-10-18. Harness v0.15.2 runs every sandbox (read from the running pod), composed by crossplane-configuration v0.9.15. Each row below carries one of four marks:

The loop

agent-run is the container’s entrypoint (tini -- agent-run). It does five things, and agent-server does the rest:

    sequenceDiagram
  autonumber
  participant AR as agent-run
  participant AS as agent-server (127.0.0.1:8000)
  participant LLM as agent-router /v1 (via identity-proxy)
  participant MCP as agent-router /mcp
  participant GH as GitHub
  AR->>AS: start, wait /ready (120 s)
  AR->>GH: clone, then check out origin/branch if pushed, else baseRef
  AR->>AS: POST /api/conversations (task.md, rules.md, LLM, tools, MCP)
  loop each iteration, at most 500
    AS->>AS: condenser: summarise if over 80 events or the context window
    AS->>LLM: chat completion (timeout 300 s, reasoning_effort high)
    LLM-->>AS: tool calls
    AS->>AS: terminal / file_editor / task_tracker / MCP tool
    AS->>MCP: platform tools, room_* tools
    AS->>AS: stuck detector over the last 20 events
  end
  loop every 15 s
    AR->>AS: GET status and new events
    AR->>AR: print "agent-run step N" lines, post milestone notes
  end
  AS-->>AR: execution_status finished | error | stuck
  AR->>AR: summary line, final read by the room-bridge
  AR->>AS: stop
  AR->>GH: revoke the run's token
  Note over AR: exit 0 on finished, 1 otherwise: the claim's phase
  

The step log is what you read most. One line per action, the final message in full:

agent-run step 3: terminal | List crossplane controller dir and kustomization | ls /workspace/repo/... | trace_id=706f…
agent-run model retry 1/2 in 10s: ServiceUnavailableError litellm.ServiceUnavailableError: …
agent-run: conversation ended with execution_status=finished
agent-run summary: 21 steps, 0 model retries
agent-run final message:
…

Actions are printed, their outputs never are, and every line is redacted for GitHub tokens before it is written. Condensations are not in the step log.

Where each setting comes from

Five layers, each in its own repository, each released and pinned into the next. A run’s settings are fixed at creation: the claim’s fields are immutable, except budget.maxTokens.

    flowchart TB
  subgraph F["Factory config · ai-native-ref"]
    FC["tooling/base/agent-factory/helm-values-configmap.yaml<br/>tiers · templates · caps · resume · meter.prices<br/>+ gcp-0 overlay: sandbox.suspend"]
  end
  subgraph T["Triage · agent-platform factory"]
    TR["class × tier matrix → template<br/>tier → model, runTokens, runMinutes, runUSD"]
  end
  subgraph C["AgentRun claim · XRD in crossplane-configuration"]
    CL["role · dataClass · model · budget.maxTokens · budget.maxMinutes<br/>size · egress.profiles · roomRef · suspendable"]
  end
  subgraph K["Composition · crossplane-configuration apis/agentrun/kcl/main.k"]
    KC["harness image digest · size → CPU/memory/scratch<br/>activeDeadlineSeconds · egress FQDNs · grace<br/>env: MODEL, DATA_CLASS, LLM_BASE_URL, MCP_URL · rules.md · task.md"]
  end
  subgraph H["Harness image · agent-platform images/agent-harness"]
    HC["agent_run.py: LLM, max_iterations, retries, prompt cache<br/>SDK defaults: condenser, stuck detector, timeout, tools"]
  end
  subgraph G["Gateway · ai-native-ref infrastructure/base/agent-gateway"]
    GC["model alias per listener · MCP allow list per role · budgets B1/B2"]
  end
  API["Run API · task agent:run<br/>model, maxTokens, profiles, room"] --> C
  F --> T --> C --> K --> H
  H -- "every model and tool call" --> G
  

Only the factory may create an AgentRun (a Kyverno policy refuses everyone else), so a run you start by hand also goes through the factory’s run API.

Knob reference

Factory: tiers

config.tiers in tooling/base/agent-factory/helm-values-configmap.yaml. Exactly light, standard and frontier; triage fixes one per task, and each run of the task inherits it. deployed, the USD cap live (below).

A priced run is held to its USD cap, not to its tokens: kk2egjta (frontier) passed 12.5 M tokens against a 4 M maxTokens at $4.46 of its $6.80 on 2026-10-18, because 95% of them were cache reads at $0.26 per million. The gateway’s own per-run budget B1 (5 M reference tokens, $8.50) is the backstop, still in shadow (gateways).

Factory: templates and triage

config.templates: which roles run, in order, on one branch. deployed.

Triage picks the template from the task’s class and tier, not from defaults.template:

The tier comes from the complexity classifier, which is design: it is not deployed, so every task falls back to standard (status.classification.classifier: static). triage.controlPercent: 10 puts one task in ten, by a hash of its id, in the control group, which runs frontier. On 2026-10-18 the twelve tasks on gcp-0 were ten standard and two frontier, both control. defaults.template and defaults.tier are validated but read only by the static triager, which the deployed factory does not use: editing them changes nothing.

The reviewer runs on the other tier (“on a different tier from the implementer where possible”): standard and light implementers get a frontier reviewer, a frontier implementer a standard one. The reviewer gets that tier’s label, model and USD cap, and keeps the implementer’s maxTokens (live: ujnumrm6, reviewer, tier frontier, maxTokens 1,500,000). The tester keeps the implementer’s tier.

Factory: caps, resume and suspend

Run API: runs started by hand

task agent:run -- --role … --class … --task … asks the factory for one run. Such a run has no tier, so the meter caps it in tokens: --max-tokens (default 2,000,000, at most 5,000,000). --model takes one of the four logical names (default agent-default), --profiles the egress profiles. The deadline is fixed at 120 minutes and the size at small: --minutes and --size are refused. Live example: jede5jsq, an open-ended typo hunt, 55 steps, revoked at 2.2 M tokens on 2026-10-18 (limit run-tokens).

AgentRun claim

The XRD, agentruns.cloud.ogenki.io (definition). The factory always writes size: small, baseRef: main for an implementer and the task branch for a reviewer or tester.

Composition

apis/agentrun/kcl/main.k turns the claim into the pod. Nothing here is set per run.

Harness

Set in agent_run.py and site/sitecustomize.py, or left at the SDK’s v1.49.6 defaults. None is a claim field.

Trade-offs

Measuring a change

Change one knob, run the same kind of task, and compare these. Every query names a run by its id, the 8 characters after xplane-run-.

# One run's cost by model and token type, priced as the meter does
sum by (gen_ai_request_model, gen_ai_token_type) (
  max_over_time(gen_ai_client_token_usage_sum{ar_agent="system:serviceaccount:agents:xplane-run-<id>"}[1d]))

# The run's step log, then its tool mix
kubernetes.pod_namespace:"agents" AND kubernetes.pod_name:"xplane-run-<id>" AND kubernetes.container_name:"harness" AND _msg:~"^agent-run"
kubernetes.pod_name:"xplane-run-<id>" AND kubernetes.container_name:"harness" AND _msg:~"^agent-run step "
  | extract "agent-run step <n>: <tool> |" | stats by (tool) count() steps

What runs look like

Factory and hand-started runs on gcp-0, read from VictoriaMetrics and VictoriaLogs on 2026-10-18. All on glm-5.3; cost is the meter’s agent_factory_run_spend_usd.

Gateway latency for these runs’ model calls over the two days: p50 2.7 s, p95 18.3 s.

What the numbers say:

• Step count, not tier, separates the runs. Most finish in 10–40 steps and under $0.20; the two dashboard tasks ran 300–450 steps.
• 95% of public input is cache reads, so a run’s cost is roughly 0.26 × input + 1.14 × uncached input + 4.40 × output per million on GLM-5.3. Uncached input and output are each under 10% of the bill’s tokens, but together about 30% of its dollars.
• A token cap would mislead here. d3jacb5z reached 7.7 M tokens before its $2.55; under the old token cap it would have stopped at 1.5 M, which is what decided 11 of 15 issues in the v2 cohort.

Failure modes

Recipes

Make reviews cheaper

A review is short when the PR is: the two on 2026-10-18 took 7 and 9 steps and under 135 k input tokens. Its cost is in the rounds, not the run.

1. Keep maxReviewRounds at 2, or set it to 1 for a class whose fixes are mechanical.
2. Let docs-links stay solo (the matrix already skips the reviewer below frontier).
3. To run the reviewer on a smaller model, set templates.pair.reviewerModel: tier-standard (glm-5.3-flashx on public). ADR-0058 weighed it: cheaper, but a smaller model judging a larger one’s work. It keeps the other tier’s USD cap.
4. Do not move the reviewer to a lower tier to cap it: the reviewer’s cap is the other tier’s runUSD, and a short review never reaches it.

Give long tasks more room

1. Measure first: is the run long because the work is large, or because it wanders? A large run commits along the way (committed., pushed its branch. notes); a wandering one shows hundreds of reads and no commit.
2. For large work, raise the tier’s runUSD and runMinutes together, and keep taskUSD ≥ 2 × runUSD so a resume still fits. Bounds: runMinutes ≤ 480, runTokens ≤ 5 M.
3. Expect frontier only from the 10% control group until the complexity classifier lands.
4. A task needing pypi, npm, golang or crates needs the profile on its run; the factory writes none on its own, so start it through the run API with --profiles.

Debug a run that loops

    flowchart TD
  A["Run is long or ended badly"] --> B{"execution_status?"}
  B -- stuck --> S["Same action/error repeated:<br/>read the last 20 steps,<br/>fix the tool, host or test it trips on"]
  B -- error --> E{"agent-run error line?"}
  E -- "maximum iterations" --> L
  E -- "LLMServiceUnavailable" --> P["Provider: retry the task"]
  E -- "timeout" --> R["Reasoning too long:<br/>check reasoning_effort"]
  B -- "none: revoked or deadline" --> L{"Step mix"}
  L -- "mostly terminal reads,<br/>no commit" --> W["Wandering:<br/>scope the task, add an exit"]
  L -- "commits, checks, pushes" --> G["Large work:<br/>more runUSD + runMinutes"]
  L -- "same refused action<br/>in a room" --> Q["Bridge refusals:<br/>read the room, approve,<br/>or fork with egress"]
  

1. kubectl get agentrun -n agents xplane-run-<id>: phase and reason.
2. The step log’s last 30 lines: are the commands repeating, or changing?
3. The tool mix (the LogsQL above): a run that is 95% terminal reads and has no commit milestone is searching, not working. d3jacb5z: 303 of 319 steps terminal, 5 file_editor.
4. The room transcript: the model’s reasoning, which the step log leaves out.
5. The trace: one span per model and tool call, with timings.
6. Stop it early if it is burning money: delete the claim, or factory/stop on the issue.

What is not tunable today

Related: Runtime for the isolation, Factory for the task flow, Rooms for approvals, Observability for the signals, and the user guide for budgets from a developer’s seat.