NOnodus-compute
Managed agents

Create a bounded group on one agent definition

Changed on

Requires explicit group admission entitlement and an owned agent definition. Pins one definition revision. The same submission key and body recover the same group after an uncertain response, including when new admission is disabled. Group limits cannot raise the deployment worker or spending limit.

post/v1/agent-groups

Request

  • Base URL
    / (relative, and the document was published on a file host, not at the API’s origin)
  • Auth
    HTTP bearer

Headers

Idempotency-Keystring required

Stable key for this logical operation. Reuse the same key and body after an uncertain response.

Request body

attempt_budget_usdnumber nullable

Optional fixed attempt reservation in whole microdollars. It can narrow the selected revision cap. Omission inherits that revision cap.

namestring required
agent_idstring required
revisioninteger

Omit or use zero to pin the current definition revision when the group is created.

budget_usdnumber

Omit or use zero for account funding without a group spending limit. An explicit positive value is a compute sublimit of any positive deployment budget. Payment, available credits, deployment limits and accepted attempt limits still apply. This does not create a second funded balance.

max_activeinteger required

Authorized attempts in admitting, starting or running state, including retained waiting workers. This is not measured productive concurrency.

max_heldinteger required

Allocations awaiting confirmed physical cleanup, including provisioning, draining and uncertain resources. Pending accounting retains spending reservations after physical capacity is released. Must be at least max_active and at most the deployment worker limit.

max_pendinginteger

All nonterminal tasks, including active, waiting and blocked work. Omit or use zero for the smaller of 1000 and the account entitlement.

Response

Accepted

attempt_budget_usdnumber nullable

Immutable fixed attempt reservation accepted for this group and its child runs. Absent for the legacy allocation policy.

idstring required
namestring required
agent_idstring required
revisioninteger required
status'active' | 'cancelled' required

Admission lifecycle. Use logical_runs for task progress and allocations for remaining cleanup.

budget_usdnumber required

Zero means account funding without a group spending limit. A positive value is the group's accepted compute sublimit of any positive deployment budget. Payment, available credits, deployment limits and accepted attempt limits still apply.

max_activeinteger required

Authorized attempts in admitting, starting or running state, including retained waiting workers. This is not measured productive concurrency.

max_heldinteger required

Allocations awaiting confirmed physical cleanup, including provisioning, draining and uncertain resources. Pending accounting retains spending reservations after physical capacity is released. Must be at least max_active and at most the deployment worker limit.

max_pendinginteger required
max_retained_runsinteger required

Persisted admission cap for runs whose payloads have not expired. Completion alone does not release this count.

created_atstring date-time required
cancelled_atstring date-time nullable required
retained_runsinteger required
cost_usdnumber required

Settled attempt costs and recorded compute charges for unsettled attempts without a spending cap, within the deployment account.

reserved_usdnumber required

Full accepted budget liability of unsettled assigned attempts with a spending cap, plus outstanding account funding reservations for attempts without a cap. A closed marker alone cannot release these reservations.

active_authorized_attemptsinteger required

Attempts in admitting, starting or running state. Includes retained waiting or recovering workers and does not establish productive activity.

work_status'empty' | 'pending' | 'running' | 'waiting' | 'blocked' | 'completed' | 'cancelled' | 'cancelling' required

Read-only summary of the current logical runs, independent of group admission and remaining cleanup.

cleanup_status'complete' | 'pending' | 'unresolved' required

Separate from useful task completion. Unresolved resource, accounting or message publication evidence takes precedence, followed by pending allocation or inbox cleanup.

peer_messagingboolean

Read-only availability of direct task messaging, assigned automatically when this group is admitted on a supported deployment. Existing groups retain their original availability.

Changes