io.enterpriseai.resources.RunsClient
Source: sdks/java/enterprise-ai-java/src/main/java/io/enterpriseai/resources/RunsClient.java. Back to the Java SDK reference index.
This page is generated by tools/docs/gen_sdk_reference.py from the SDK sources and the OpenAPI text folders. Do not edit it by hand: change the source and regenerate.
Class RunsClient
Runs (Execution Contract), steps, replay, events and subagents.
Constructor RunsClient
RunsClient(Transport transport)
Creates the client on the shared transport; EnterpriseAIClient builds it and exposes it through the accessor of the same name.
| Name | Type | Default | Required | Description |
|---|---|---|---|---|
transport | Transport | yes | Transport shared by the sub-clients of one client. |
RunsClient.addStep
JsonNode addStep(String id, Object body)
Report a step of a run. Records one step reported by the runtime and returns the decision of the Loop Controller: run_state, next_kind, retry, backoff_seconds, error, approval_id and the budgets. Needs tenant_admin, developer or agent. Steps: 1. The Kill Switch Registry and, for a sensitive step, the delegation chain, session and policy are checked. 2. A pending run moves to running; any other state than running answers 409 run_not_running. 3. Usage and cost are added to the budget consumption (cost in the run currency, else 400 invalid_request). 4. A step matching autonomy.human_approval_for without approval_id stays pending, an approval is opened and the run moves to waiting_approval; a step of kind approval with state pending opens an approval with quorum. 5. Budgets, max steps and retries decide the next state (failed or timed_out when exceeded).
Route: /v1/runs/{run_id}/steps (POST).
| Name | Type | Default | Required | Description |
|---|---|---|---|---|
id | String | yes | Identifier (UUID) of the run. | |
body | Object | yes | The step: kind, state, usage, cost, error and run state hints. |
Returns: JsonNode. Decoded JSON answer of the operation "Report a step of a run".
Raises: the typed errors of the transport (Errors).
RunsClient.addStep
JsonNode addStep(String id, Object body, RequestOptions options)
Report a step of a run. Records one step reported by the runtime and returns the decision of the Loop Controller: run_state, next_kind, retry, backoff_seconds, error, approval_id and the budgets. Needs tenant_admin, developer or agent. Steps: 1. The Kill Switch Registry and, for a sensitive step, the delegation chain, session and policy are checked. 2. A pending run moves to running; any other state than running answers 409 run_not_running. 3. Usage and cost are added to the budget consumption (cost in the run currency, else 400 invalid_request). 4. A step matching autonomy.human_approval_for without approval_id stays pending, an approval is opened and the run moves to waiting_approval; a step of kind approval with state pending opens an approval with quorum. 5. Budgets, max steps and retries decide the next state (failed or timed_out when exceeded).
Route: /v1/runs/{run_id}/steps (POST).
| Name | Type | Default | Required | Description |
|---|---|---|---|---|
id | String | yes | Identifier (UUID) of the run. | |
body | Object | yes | The step: kind, state, usage, cost, error and run state hints. | |
options | RequestOptions | yes | Per call options (idempotency key, traceparent, headers, abort signal). |
Returns: JsonNode. Decoded JSON answer of the operation "Report a step of a run".
Raises: the typed errors of the transport (Errors).
RunsClient.cancel
JsonNode cancel(String id)
Cancel a run. Moves the run to cancelled with the error cancelled; its active sub-agent runs are cancelled too. Needs tenant_admin, developer, agent or security_officer. A run already terminal answers 409 invalid_transition. Audited as run.transition.
Route: /v1/runs/{run_id}/cancel (POST).
| Name | Type | Default | Required | Description |
|---|---|---|---|---|
id | String | yes | Identifier (UUID) of the run. |
Returns: JsonNode. Decoded JSON answer of the operation "Cancel a run".
Raises: the typed errors of the transport (Errors).
RunsClient.cancel
JsonNode cancel(String id, Object body)
Cancel a run. Moves the run to cancelled with the error cancelled; its active sub-agent runs are cancelled too. Needs tenant_admin, developer, agent or security_officer. A run already terminal answers 409 invalid_transition. Audited as run.transition.
Route: /v1/runs/{run_id}/cancel (POST).
| Name | Type | Default | Required | Description |
|---|---|---|---|---|
id | String | yes | Identifier (UUID) of the run. | |
body | Object | yes | Optional reason of the cancellation. |
Returns: JsonNode. Decoded JSON answer of the operation "Cancel a run".
Raises: the typed errors of the transport (Errors).
RunsClient.events
SseStream events(String id)
Stream the events of a run. Server-Sent Events stream (text/event-stream) of the run events: run.created, run.state, step.recorded, checkpoint.created, subagent.spawned. Each message carries id, event and data (type, data, at). Steps: 1. The events already recorded after Last-Event-ID are sent. 2. Without follow the stream ends at once; with follow=true it polls every second. 3. The stream ends with an end event carrying the run state when the run is terminal, when timeout has elapsed or when the client disconnects. 404 run_not_found.
Route: /v1/runs/{run_id}/events (GET).
| Name | Type | Default | Required | Description |
|---|---|---|---|---|
id | String | yes | Identifier (UUID) of the run. |
Returns: SseStream. A SseStream: Blocking Server-Sent Events reader. Use it with try-with-resources, as an Iterator, a Stream or a reactive Flow.Publisher. A data: [DONE] event ends the stream.
Raises: the typed errors of the transport (Errors).
RunsClient.get
ExecutionContract get(String id)
Get a run. Returns the Execution Contract v1 of the run: agent and version, task, state, steps, budget limits and consumption, errors, retry policy, resume information and trace. 404 run_not_found.
Route: /v1/runs/{run_id} (GET).
| Name | Type | Default | Required | Description |
|---|---|---|---|---|
id | String | yes | Identifier (UUID) of the run. |
Returns: ExecutionContract. A ExecutionContract: Execution Contract v1 (contracts/v1/execution-contract.schema.json): state, steps and budgets of one run.
Raises: the typed errors of the transport (Errors).
RunsClient.getRaw
JsonNode getRaw(String id)
Get a run. Returns the Execution Contract v1 of the run: agent and version, task, state, steps, budget limits and consumption, errors, retry policy, resume information and trace. 404 run_not_found.
Route: /v1/runs/{run_id} (GET).
| Name | Type | Default | Required | Description |
|---|---|---|---|---|
id | String | yes | Identifier (UUID) of the run. |
Returns: JsonNode. Decoded JSON answer of the operation "Get a run".
Raises: the typed errors of the transport (Errors).
RunsClient.list
Page<JsonNode> list()
List the runs. Runs of the tenant, newest first, paginated with cursor. Filters: agent_id (id or name; agent is an alias), state, session_id, parent_run_id. An unknown state or a malformed UUID answers 400 invalid_request.
Route: /v1/runs (GET).
This element takes no parameter.
Returns: Page<JsonNode>. A Page: One page of a cursor paginated collection ({"items": [...], "next_cursor": "..."|null}).
Raises: the typed errors of the transport (Errors).
RunsClient.list
Page<JsonNode> list(Map<String, ?> query)
List the runs. Runs of the tenant, newest first, paginated with cursor. Filters: agent_id (id or name; agent is an alias), state, session_id, parent_run_id. An unknown state or a malformed UUID answers 400 invalid_request.
Route: /v1/runs (GET).
| Name | Type | Default | Required | Description |
|---|---|---|---|---|
query | Map<String, ?> | yes | Query string parameters of the route. |
Returns: Page<JsonNode>. A Page: One page of a cursor paginated collection ({"items": [...], "next_cursor": "..."|null}).
Raises: the typed errors of the transport (Errors).
RunsClient.replay
JsonNode replay(String id)
Replay a run. Returns the full history of a run for review: its Execution Contract, steps, checkpoints, the audit events that name it and a single timeline sorted by time (run events and audit events). Needs tenant_admin, developer, agent, auditor or security_officer. Read only: nothing is re-executed.
Route: /v1/runs/{run_id}/replay (GET).
| Name | Type | Default | Required | Description |
|---|---|---|---|---|
id | String | yes | Identifier (UUID) of the run. |
Returns: JsonNode. Decoded JSON answer of the operation "Replay a run".
Raises: the typed errors of the transport (Errors).
RunsClient.resume
JsonNode resume(String id)
Resume a run. Moves a suspended, failed, timed_out or waiting_input run back to running (else 409 invalid_transition). Needs tenant_admin, developer or agent; the agent must be active (409 agent_not_active). Strategies: 1. from_last_checkpoint (default, except for waiting_input): resume from checkpoint_id or the last checkpoint (409 no_checkpoint if none). 2. restart_step (default for waiting_input): replay the current step. 3. restart_run: start over with the budget consumption reset. A run that failed on budget_exceeded, max_steps_exceeded, killed or approval_rejected can only use restart_run (409 run_not_resumable). Returns the run and the checkpoint used.
Route: /v1/runs/{run_id}/resume (POST).
| Name | Type | Default | Required | Description |
|---|---|---|---|---|
id | String | yes | Identifier (UUID) of the run. |
Returns: JsonNode. Decoded JSON answer of the operation "Resume a run".
Raises: the typed errors of the transport (Errors).
RunsClient.resume
JsonNode resume(String id, Object body)
Resume a run. Moves a suspended, failed, timed_out or waiting_input run back to running (else 409 invalid_transition). Needs tenant_admin, developer or agent; the agent must be active (409 agent_not_active). Strategies: 1. from_last_checkpoint (default, except for waiting_input): resume from checkpoint_id or the last checkpoint (409 no_checkpoint if none). 2. restart_step (default for waiting_input): replay the current step. 3. restart_run: start over with the budget consumption reset. A run that failed on budget_exceeded, max_steps_exceeded, killed or approval_rejected can only use restart_run (409 run_not_resumable). Returns the run and the checkpoint used.
Route: /v1/runs/{run_id}/resume (POST).
| Name | Type | Default | Required | Description |
|---|---|---|---|---|
id | String | yes | Identifier (UUID) of the run. | |
body | Object | yes | Optional checkpoint and resume strategy. |
Returns: JsonNode. Decoded JSON answer of the operation "Resume a run".
Raises: the typed errors of the transport (Errors).
RunsClient.spawnSubagent
JsonNode spawnSubagent(String id, Object body)
Spawn a sub-agent run. Starts a child run from a pending or running parent (else 409 run_not_running) and returns its Execution Contract. Needs tenant_admin, developer or agent and the scope agents:run. Checks, in order: the Kill Switch Registry; the depth against autonomy.max_depth (default 1, 409 subagent_depth_exceeded); the number of children against autonomy.max_subagents (default 3, 409 subagent_count_exceeded); the child agent against the subagents list of the parent manifest (403 subagent_not_allowed); the parent delegation. The child budget cannot exceed what the parent has left, the child joins the parent session, and a running parent records a subagent step.
Route: /v1/runs/{run_id}/subagents (POST).
| Name | Type | Default | Required | Description |
|---|---|---|---|---|
id | String | yes | Identifier (UUID) of the parent run. | |
body | Object | yes | Child agent, task and budget. |
Returns: JsonNode. Decoded JSON answer of the operation "Spawn a sub-agent run".
Raises: the typed errors of the transport (Errors).
RunsClient.spawnSubagent
JsonNode spawnSubagent(String id, Object body, RequestOptions options)
Spawn a sub-agent run. Starts a child run from a pending or running parent (else 409 run_not_running) and returns its Execution Contract. Needs tenant_admin, developer or agent and the scope agents:run. Checks, in order: the Kill Switch Registry; the depth against autonomy.max_depth (default 1, 409 subagent_depth_exceeded); the number of children against autonomy.max_subagents (default 3, 409 subagent_count_exceeded); the child agent against the subagents list of the parent manifest (403 subagent_not_allowed); the parent delegation. The child budget cannot exceed what the parent has left, the child joins the parent session, and a running parent records a subagent step.
Route: /v1/runs/{run_id}/subagents (POST).
| Name | Type | Default | Required | Description |
|---|---|---|---|---|
id | String | yes | Identifier (UUID) of the parent run. | |
body | Object | yes | Child agent, task and budget. | |
options | RequestOptions | yes | Per call options (idempotency key, traceparent, headers, abort signal). |
Returns: JsonNode. Decoded JSON answer of the operation "Spawn a sub-agent run".
Raises: the typed errors of the transport (Errors).
RunsClient.start
JsonNode start(String agentId, Object body)
Start a run of an agent. Creates a run and returns its Execution Contract (201). Needs tenant_admin, developer or agent, the scope agents:run and the ReBAC relation can_invoke. Steps: 1. The agent must be active (else 409 agent_not_active, audited as a denial). 2. The policy agent.run is evaluated with the agent risk, owner, purpose and the data_classification of the task (403 policy_denied). 3. The budget is the manifest budget, tightened by budgets (a request can never loosen it; 422 invalid_budget). 4. The delegation and workload identity are attached, the run is created in pending (or running with start=true) and audited as run.create. A repeated Idempotency-Key returns the first run; the same key for another agent answers 409 idempotency_conflict. An unknown session_id answers 404 session_not_found.
Route: /v1/agents/{agent_id}/runs (POST).
| Name | Type | Default | Required | Description |
|---|---|---|---|---|
agentId | String | yes | Identifier (UUID) or name of the agent. | |
body | Object | yes | Task of the run, optional session, budget, retry policy and delegation. |
Returns: JsonNode. Decoded JSON answer of the operation "Start a run of an agent".
Raises: the typed errors of the transport (Errors).
RunsClient.start
JsonNode start(String agentId, Object body, RequestOptions options)
Start a run of an agent. Creates a run and returns its Execution Contract (201). Needs tenant_admin, developer or agent, the scope agents:run and the ReBAC relation can_invoke. Steps: 1. The agent must be active (else 409 agent_not_active, audited as a denial). 2. The policy agent.run is evaluated with the agent risk, owner, purpose and the data_classification of the task (403 policy_denied). 3. The budget is the manifest budget, tightened by budgets (a request can never loosen it; 422 invalid_budget). 4. The delegation and workload identity are attached, the run is created in pending (or running with start=true) and audited as run.create. A repeated Idempotency-Key returns the first run; the same key for another agent answers 409 idempotency_conflict. An unknown session_id answers 404 session_not_found.
Route: /v1/agents/{agent_id}/runs (POST).
| Name | Type | Default | Required | Description |
|---|---|---|---|---|
agentId | String | yes | Identifier (UUID) or name of the agent. | |
body | Object | yes | Task of the run, optional session, budget, retry policy and delegation. | |
options | RequestOptions | yes | Per call options (idempotency key, traceparent, headers, abort signal). |
Returns: JsonNode. Decoded JSON answer of the operation "Start a run of an agent".
Raises: the typed errors of the transport (Errors).
RunsClient.steps
JsonNode steps(String id)
List the steps of a run. Steps of the run in order, each with seq, kind, state, attempt, tokens, cost and error when present. One page only. 404 run_not_found.
Route: /v1/runs/{run_id}/steps (GET).
| Name | Type | Default | Required | Description |
|---|---|---|---|---|
id | String | yes | Identifier (UUID) of the run. |
Returns: JsonNode. Decoded JSON answer of the operation "List the steps of a run".
Raises: the typed errors of the transport (Errors).
RunsClient.subagents
JsonNode subagents(String id)
List the sub-agent runs. Summaries of the child runs started by this run, oldest first. One page only. 404 run_not_found.
Route: /v1/runs/{run_id}/subagents (GET).
| Name | Type | Default | Required | Description |
|---|---|---|---|---|
id | String | yes | Identifier (UUID) of the parent run. |
Returns: JsonNode. Decoded JSON answer of the operation "List the sub-agent runs".
Raises: the typed errors of the transport (Errors).