self_hosted Environment. A worker polls for queued Session work, acknowledges the item it will run, keeps the lease alive with heartbeats, and stops the item when the work is complete or must be aborted.
Work item object
Returned by list, poll, get, update metadata, acknowledge, and stop endpoints.| Field | Type | Description |
|---|---|---|
id | string | Work item ID with the work_ prefix |
type | string | Always "work" |
environment_id | string | Environment ID with the env_ prefix |
data | object | Work payload descriptor |
data.type | string | Currently always "session" |
data.id | string | Session ID with the sess_ prefix |
state | string | Work item state. See Work states |
created_at | string | Creation time in UTC |
acknowledged_at | string|null | Time when a worker acknowledged the item, or null before ack |
started_at | string|null | Time when the first heartbeat moved the item to active, or null before start |
latest_heartbeat_at | string|null | Latest heartbeat timestamp, or null before the first heartbeat |
stop_requested_at | string|null | Time when a graceful stop was requested, or null |
stopped_at | string|null | Time when the item reached stopped, or null while live |
metadata | object | String-only metadata associated with the work item |
Work states
| State | Description |
|---|---|
queued | The work item is available to poll, or was delivered but not yet acknowledged |
starting | A worker acknowledged the item and should begin executing it |
active | A worker sent a heartbeat and owns the current lease |
stopping | A graceful stop was requested; the worker should drain and confirm stop |
stopped | The item is no longer live and cannot be heartbeated |
Work metadata
Work metadata is a string-only map. When a Session creates a work item, the Session metadata is projected into this string map. Use Update work item metadata to merge changes:- String values upsert a key.
nulldeletes a key.- Omitting
metadataleaves the current metadata unchanged.
Work heartbeat object
Returned by Send work heartbeat.| Field | Type | Description |
|---|---|---|
type | string | Always "work_heartbeat" |
last_heartbeat | string | Server timestamp for the accepted heartbeat |
lease_extended | boolean | Always true for a successful heartbeat |
state | string | Current work item state after the heartbeat |
ttl_seconds | integer | Current lease TTL in seconds |
Work queue stats object
Returned by Get work queue stats.| Field | Type | Description |
|---|---|---|
type | string | Always "work_queue_stats" |
depth | integer | Queued items currently claimable by workers |
pending | integer | Queued items delivered recently but not yet acknowledged |
oldest_queued_at | string|null | Creation time of the oldest queued item, or null when the queue is empty |
workers_polling | integer | Distinct Worker-ID values that polled this environment in the last 30 seconds |
Related
Cloud environment setup
Choose the container, network, and dependencies your agent runs in.