Agent Runtime
Ad-hoc LLM agent runs
Ad-hoc LLM agent runs
Every request needs a credential — see Authentication.
| Method | Path | Summary |
|---|---|---|
POST | /sandbox/agent/agents | Register Agent |
GET | /sandbox/agent/agents/{agent_id} | Get Agent |
GET | /sandbox/agent/capabilities | List agents (catalog-backed) |
GET | /sandbox/agent/v1/agents | List Agents |
POST | /sandbox/agent/v1/runs | Start Agent Run |
GET | /sandbox/agent/v1/runs/{job_id} | Agent run status |
GET | /sandbox/agent/v1/runs/{job_id}/events | SSE agent run events |
Common headers
Accepted on every endpoint on this page.
| Name | In | Type | Required | Description |
|---|---|---|---|---|
x-correlation-id | header | string | no | End-to-end correlation id for this eval run. When set, the gateway and downstream services honor it verbatim in logs, Cloud Trace span attributes, async job payloads, and Langfuse trace.id. When omitted, the gateway generates a ULID and echoes it on the response. |
Endpoints
Register Agent
POST /sandbox/agent/agents
Request body
application/json, required — RegisterRequest
| Field | Type | Required | Description |
|---|---|---|---|
id | string | yes | |
display_name | string | null | no | |
requires_model | boolean | no | Default: true. |
mcp_adapter | string | null | no | |
air_gap_capable | boolean | no | Default: false. |
requires_reference_solution | boolean | no | Default: false. |
Responses
| Status | Description | Body |
|---|---|---|
201 | Successful Response | AgentOut |
422 | Validation Error | HTTPValidationError |
Get Agent
GET /sandbox/agent/agents/{agent_id}
Parameters
| Name | In | Type | Required | Description |
|---|---|---|---|---|
agent_id | path | string | yes |
Responses
| Status | Description | Body |
|---|---|---|
200 | Successful Response | AgentOut |
404 | No agent with this id. Agents come from the catalog, so an id that worked before can disappear when a catalog entry is disabled — list /agents rather than hardcoding one. | — |
422 | Validation Error | HTTPValidationError |
List agents (catalog-backed)
GET /sandbox/agent/capabilities
Responses
| Status | Description | Body |
|---|---|---|
200 | Successful Response | object |
List Agents
GET /sandbox/agent/v1/agents
Tier 1 catalog entries plus Harbor AgentFactory agents (deduped).
Responses
| Status | Description | Body |
|---|---|---|
200 | Catalog ∪ Harbor factory agents | object |
Example response:
{
"agents": [
{
"id": "oracle",
"display_name": "Oracle",
"source": "catalog"
},
{
"id": "opencode",
"display_name": "OpenCode",
"source": "catalog"
}
],
"count": 2
}Start Agent Run
POST /sandbox/agent/v1/runs
Parameters
| Name | In | Type | Required | Description |
|---|---|---|---|---|
X-Sandbox-Project-Id | header | string | null | no | Project to bill and rate-limit this request against. Validated against the credential: a project-scoped token may only name its own project, and gets 403 otherwise. Defaults to the token's project when omitted. |
X-Sandbox-Tenant-Id | header | string | null | no | Tenant for this request. Must match the credential's tenant when the credential carries one. |
Request body
application/json, required — AgentRunBody
| Field | Type | Required | Description |
|---|---|---|---|
agent_id | string | yes | |
instruction | string | yes | |
model | string | null | no | |
workspace | object | null | no | |
sandbox_id | string | null | no | Existing long-lived sandbox for a continuing, ungraded agent loop. Only agents whose catalog integration is sandbox may attach. The sandbox must be running and owned by this tenant/project. |
pass_at_k | integer | no | Agent Runtime is ungraded and normally runs once. Values above 1 are rejected when sandbox_id is set; use Harbor pass_at_k for fresh attempts. Default: 1. |
agent_options | object | null | no | Executor options for this run: agent_env, agent_kwargs, sandbox, n_concurrent, custom_agent_import. When agent_id is opencode: opencode_agent sets default_agent in opencode.json (plan | build); opencode_config deep-merges an allowlisted subset of opencode.json (agent, permission, tools, model, small_model, subagent_depth, instructions, command, mcp) — e.g. a custom agent.review subagent. Accepted as harbor_extensions (deprecated) for backwards compatibility. |
Example:
{
"agent_id": "opencode",
"instruction": "List files in the workspace root.",
"model": "anthropic/claude-sonnet-4-5",
"agent_options": {
"agent_env": {
"SANDBOX_DOCS": "1"
}
}
}Responses
| Status | Description | Body |
|---|---|---|
202 | Run accepted | object |
400 | The agent's preconditions are not satisfied by this request | — |
422 | Validation Error | HTTPValidationError |
Example response:
{
"job_id": "agent-run-550e8400",
"status": "queued",
"agent_id": "opencode",
"message": "run accepted",
"status_url": "/sandbox/agent/v1/runs/agent-run-550e8400",
"events_url": "/sandbox/agent/v1/runs/agent-run-550e8400/events"
}Agent run status
GET /sandbox/agent/v1/runs/{job_id}
Status, timings and result for one agent run.
Reads the same durable record the worker writes and the harbor job route serves, so the two surfaces cannot disagree about a run.
Parameters
| Name | In | Type | Required | Description |
|---|---|---|---|---|
job_id | path | string | yes | |
X-Sandbox-Project-Id | header | string | null | no | Project to bill and rate-limit this request against. Validated against the credential: a project-scoped token may only name its own project, and gets 403 otherwise. Defaults to the token's project when omitted. |
X-Sandbox-Tenant-Id | header | string | null | no | Tenant for this request. Must match the credential's tenant when the credential carries one. |
Responses
| Status | Description | Body |
|---|---|---|
200 | Current state of the run | object |
404 | No run with this id in this tenancy | — |
422 | Validation Error | HTTPValidationError |
Example response:
{
"job_id": "agent-run-550e8400",
"status": "running",
"timings": {
"enqueued_at": 1785124565.5,
"started_at": 1785124573.5
}
}SSE agent run events
GET /sandbox/agent/v1/runs/{job_id}/events
Follow a run's phases as they happen.
The same stream generator the harbor route uses, over the same event log — an agent run and a datapoint run are narrated by one mechanism, so this is a second entrance to it rather than a second copy of it.
Parameters
| Name | In | Type | Required | Description |
|---|---|---|---|---|
job_id | path | string | yes | |
Last-Event-ID | header | string | null | no | |
X-Sandbox-Project-Id | header | string | null | no | Project to bill and rate-limit this request against. Validated against the credential: a project-scoped token may only name its own project, and gets 403 otherwise. Defaults to the token's project when omitted. |
X-Sandbox-Tenant-Id | header | string | null | no | Tenant for this request. Must match the credential's tenant when the credential carries one. |
Responses
| Status | Description | Body |
|---|---|---|
200 | Server-sent events. A meta frame arrives immediately, then one phase frame per phase transition, then done. Reconnect with Last-Event-ID to resume rather than replay. | any |
404 | No run with this id in this tenancy. The stream is refused rather than opened, so a mistyped id fails immediately instead of looking like a run that is slow to start. | — |
422 | Validation Error | HTTPValidationError |
Schemas
The object shapes referenced above.
AgentOut
| Field | Type | Required | Description |
|---|---|---|---|
id | string | yes | |
display_name | string | yes | |
requires_model | boolean | yes | |
mcp_adapter | string | null | no | |
air_gap_capable | boolean | no | Default: false. |
requires_reference_solution | boolean | no | Default: false. |
AgentRunBody
| Field | Type | Required | Description |
|---|---|---|---|
agent_id | string | yes | |
instruction | string | yes | |
model | string | null | no | |
workspace | object | null | no | |
sandbox_id | string | null | no | Existing long-lived sandbox for a continuing, ungraded agent loop. Only agents whose catalog integration is sandbox may attach. The sandbox must be running and owned by this tenant/project. |
pass_at_k | integer | no | Agent Runtime is ungraded and normally runs once. Values above 1 are rejected when sandbox_id is set; use Harbor pass_at_k for fresh attempts. Default: 1. |
agent_options | object | null | no | Executor options for this run: agent_env, agent_kwargs, sandbox, n_concurrent, custom_agent_import. When agent_id is opencode: opencode_agent sets default_agent in opencode.json (plan | build); opencode_config deep-merges an allowlisted subset of opencode.json (agent, permission, tools, model, small_model, subagent_depth, instructions, command, mcp) — e.g. a custom agent.review subagent. Accepted as harbor_extensions (deprecated) for backwards compatibility. |
HTTPValidationError
| Field | Type | Required | Description |
|---|---|---|---|
detail | ValidationError[] | no |
RegisterRequest
| Field | Type | Required | Description |
|---|---|---|---|
id | string | yes | |
display_name | string | null | no | |
requires_model | boolean | no | Default: true. |
mcp_adapter | string | null | no | |
air_gap_capable | boolean | no | Default: false. |
requires_reference_solution | boolean | no | Default: false. |
ValidationError
| Field | Type | Required | Description |
|---|---|---|---|
loc | string | integer[] | yes | |
msg | string | yes | |
type | string | yes | |
input | any | no | |
ctx | object | no |
Machine-readable spec: OpenAPI YAML.