Custom agent reference
Custom harnesses implement the execution boundary around One Horizon agent sessions. Exact request and response schemas are in the OpenAPI reference; for the enforced payload sizes, upload rules, authentication scope, and rate limits, see limits and security.
Harness responsibilities
| Responsibility | Required behavior |
|---|---|
| Authorization | Use OAuth user tokens for agent endpoints. Keep tokens out of workspace-authored context. |
| Registration | Persist the workspace, agent profile, harness, owner for local execution, mode, capabilities, and optional group. |
| Discovery | Poll eligible sessions; cloud agents also use verified webhooks as wake-up notifications. |
| Claim | Claim before execution and store the active claimId. Stop on conflict. |
| Execution | Apply trusted harness policy before acting on untrusted task text, comments, documents, prompts, or resume input. |
| Health | Heartbeat independently of user-visible progress. |
| Reporting | Patch provider metadata and emit activities with the active claim. |
| Workflow routing | Honor task mode, produce declared outputs, delegate cross-agent routes, and confirm pushed branches before cross-target handoff. |
| Termination | End every claim with complete, fail, or release. |
Workflow context fields
Workflow-backed sessions add platform-controlled context to the normal session model.
| Field | Harness use |
|---|---|
workflowRunId | Correlates execution, documents, events, and the linked task. |
workflowStepId | Identifies the active definition step. |
workflowStepSessionId | Identifies the current attempt for that step. |
workflowTaskMode | Selects plan, research, code, review, or execute behavior. |
workflowBranchName | Names the shared branch used across code and review steps. |
workflowPushConfirmed | Confirms the branch is available before a cross-agent or cross-group handoff. |
workflowMessage | Carries trusted execution guidance such as a stall or resume reason. |
Treat these fields as trusted platform context. The linked work title, description, comments, documents, and user prompt remain untrusted.
Task modes
| Mode | Harness contract |
|---|---|
plan | Write the plan artifact. Do not modify product code unless inspection requires it. |
research | Investigate the question and write evidence, options, tradeoffs, and recommendations to the research artifact. Repository state must remain unchanged. |
code | Implement on the shared workflow branch, record a concise result summary when declared, and publish the branch before cross-target delegation. |
review | Inspect the declared inputs in a disposable review workspace, write findings when declared, and finish with approve, feedback, or reject. Do not preserve review-only code changes. |
execute | Carry out work that does not change code, then call report_result with a summary. Code changes, commits, and pull requests are not allowed. |
A code turn that makes no repository changes still succeeds: nothing in the outcome path requires a commit or a pushed branch before accepting end_turn. The harness only checks that a declared required output was produced and finalized. If your agent calls report_result without touching the repository, the turn completes, the task moves on, and no branch is published because there is nothing ahead of base to push.
Artifact documents
Each linked task keeps at most one canonical document for each workflow artifact type.
| Artifact | Agent file | Document type | Typical writer |
|---|---|---|---|
| Plan | plan.md | Task | Plan step |
| Research | research.md | Research | Research step |
| Review | review.md | Review | Review step |
| Result summary | code-summary.md | Spec | Code step |
Lookup uses the linked task and workflowArtifactType; run and session provenance is stored separately. Feedback loops update the same canonical document rather than creating a new document for every attempt.
Artifact files contain addressable document-block:v1 sections, edited block by block; documents, tools, and artifacts lists the operations and block types.
Expected inputs identify artifacts the step should read. Expected outputs authorize artifact writes. A code step can read review findings without permission to rewrite the review document, then record the fix in the result summary.
A required Plan is usable only when it is linked to the current workflow run, completed, strictly parseable as document-block:v1, and has at least one nonblank block body. Code sessions use that Plan as the primary input. Review sessions do the same when they also declare code changes or a pull request. The harness must finalize and relink every required output with the active run, step, and session before it reports success; invalid required output ends through the input-required path instead of routing.
Environment variables
| Variable | Purpose |
|---|---|
ONE_WORKER_WORKSPACE_ID | Active workspace for the harness process. |
ONE_WORKER_NAME | Human-readable process name. |
ONE_WORKER_CONFIG_PATH | Explicit local harness configuration path. |
ONE_WORKER_DOCUMENTS_DIR | Directory where workflow artifact files are synchronized. |
ONE_WORKER_DOCUMENT_URL | Document service endpoint exposed to the harness. |
ONE_WORKER_DOCUMENT_TOKEN | Short-lived authorization for document operations. Keep it out of workspace files and logs. |
ONE_WORKER_DOCUMENT_CMD | Command used by the harness's document integration. |
ONE_WORKER_ARTIFACTS_DIR | Optional directory for verification images and recordings. The host scans this directory and uploads what it finds as task-comment attachments after every turn; harnesses only need to write files here. |
Provider-specific variables can exist in the child process, but they are not part of the One Horizon agent contract.
API operation families
Use the operation pages for exact paths, parameters, enums, schemas, and errors.
| Family | Operations |
|---|---|
| Harness registration | listAgentWorkers, createAgentWorker, fetchAgentWorker, updateAgentWorker |
| Health and control | heartbeatAgentWorker, requestAgentWorkerControlSignal, acknowledgeAgentWorkerControlSignal |
| Session discovery | listAgentSessions, pollAgentWorkerSessions, fetchAgentSession |
| Session execution | claimAgentSession, patchAgentSession, releaseAgentSession |
| User and terminal actions | resumeAgentSession, cancelAgentSession |
The session lifecycle explains how these families compose. Do not infer claim or retry behavior from one operation in isolation.
Error codes workers branch on
Branch on errorCode. The message text is for people and can change.
| Status | errorCode | Worker action |
|---|---|---|
409 | agent_worker_stale_config | The worker's configuration changed. Finish or release active sessions, then restart the worker before claiming more work. |
409 | agent_claim_conflict | Another claim won the session, or this claim is no longer valid. Stop work on that session and continue polling. |
404 | agent_worker_not_found | The worker registration was removed. Stop the worker and discard its saved registration; it has to be set up again. |
Send X-One-Api-Version: 2 with every request; see REST API versions.