Reference

Owner pools

An OwnerPool is the set of Agent versions qualified to own work.

Checked 2026-09-28

An OwnerPool is the set of Agent versions qualified to own work. A version joins only by passing the pool's admission suite (:qualify) and leaves automatically when a live metric regresses past a demotion rule (:observe). :run with owner_pool admits only a qualified member. The suite, the metrics and their thresholds are the caller's own; the pool stores no method of its own.

Service Sylphx Agents · Resource type agents.sylphx.com/OwnerPool · Name pattern orgs/{org}/projects/{project}/envs/{env}/owner_pools/{owner_pool} · Shape spec_status

#Fields

Field	Type	What it is
name	string	orgs/{org}/projects/{project}/envs/{env}/owner_pools/{owner_pool}.
uid	string	aop_<cell><ulid>; never reused. Output only.
meta	ResourceMeta	Resource metadata.
spec	OwnerPoolSpec	Desired state. Required.
status	OwnerPoolStatus	Observed state: the members. Output only.

#Methods

Every method of the collection, in the registry's order, with the scope it needs. The full request, response and examples are one link away.

Method	Call	What it does
GET	get	Gets an owner pool with its members.
GET	list	Lists owner pools, newest first.
POST	create	Creates an owner pool with no members. Its minimums and demotion rules are governance, so the caller needs agents:admin.
PATCH	update	Replaces an owner pool's spec (agents:admin). Members keep their standing; a changed suite or minimum applies from the next :qualify.
DELETE	delete	Deletes an owner pool and its members (agents:admin). Sessions already admitted keep running.
POST	qualify	Records an admission suite result for an Agent version. The caller holds agents:qualify and is not the principal whose create or update minted the version (PERMISSION_DENIED). Every minimum met: the member is QUALIFIED. Any score missing or below its minimum: the member is recorded REFUSED with the reason. Each qualification is recorded with its suite, suite version, result and caller; a result already recorded for the member is refused with INVALID_FIELD, so a demoted member returns only with a new suite result. A read-only version is refused with PERMISSION_DENIED; a suite or suite version other than the pool's with INVALID_FIELD. Re-qualifying keeps the member's baseline: the baseline belongs to the version and its pinned model.
POST	observe	Records a live-metric observation for a member and applies the pool's demotion rules (agents:qualify, refused to the version's authors as in :qualify). The platform computes each rule's baseline: the median of the member's first baseline_observations counted observations of the metric, set only when it is finite and positive. Values of a rule metric are lower-is-better and must not be negative. Once the baseline is set, a metric past baseline * (1 + max_regression) demotes a qualified member. Only :qualify brings a demoted member back.

#get

Gets an owner pool with its members.

GET https://api.sylphx.com/v1/orgs/acme/projects/shop/envs/production/owner_pools/owner-pool · scope agents:read · effect read · Request, response and examples

#list

Lists owner pools, newest first.

GET https://api.sylphx.com/v1/orgs/acme/projects/shop/envs/production/owner_pools · scope agents:read · effect read · paginated · Request, response and examples

#create

Creates an owner pool with no members. Its minimums and demotion rules are governance, so the caller needs agents:admin.

POST https://api.sylphx.com/v1/orgs/acme/projects/shop/envs/production/owner_pools · scope agents:admin · effect write · Request, response and examples

#update

Replaces an owner pool's spec (agents:admin). Members keep their standing; a changed suite or minimum applies from the next :qualify.

PATCH https://api.sylphx.com/v1/orgs/acme/projects/shop/envs/production/owner_pools/owner-pool · scope agents:admin · effect write · Request, response and examples

#delete

Deletes an owner pool and its members (agents:admin). Sessions already admitted keep running.

DELETE https://api.sylphx.com/v1/orgs/acme/projects/shop/envs/production/owner_pools/owner-pool · scope agents:admin · effect destructive · Request, response and examples

#qualify

Records an admission suite result for an Agent version. The caller holds agents:qualify and is not the principal whose create or update minted the version (PERMISSION_DENIED). Every minimum met: the member is QUALIFIED. Any score missing or below its minimum: the member is recorded REFUSED with the reason. Each qualification is recorded with its suite, suite version, result and caller; a result already recorded for the member is refused with INVALID_FIELD, so a demoted member returns only with a new suite result. A read-only version is refused with PERMISSION_DENIED; a suite or suite version other than the pool's with INVALID_FIELD. Re-qualifying keeps the member's baseline: the baseline belongs to the version and its pinned model.

POST https://api.sylphx.com/v1/orgs/acme/projects/shop/envs/production/owner_pools/owner-pool:qualify · scope agents:qualify · effect write · Request, response and examples

#observe

Records a live-metric observation for a member and applies the pool's demotion rules (agents:qualify, refused to the version's authors as in :qualify). The platform computes each rule's baseline: the median of the member's first baseline_observations counted observations of the metric, set only when it is finite and positive. Values of a rule metric are lower-is-better and must not be negative. Once the baseline is set, a metric past baseline * (1 + max_regression) demotes a qualified member. Only :qualify brings a demoted member back.

POST https://api.sylphx.com/v1/orgs/acme/projects/shop/envs/production/owner_pools/owner-pool:observe · scope agents:qualify · effect write · Request, response and examples