Worker lifecycle

Use this reference with the complete developer tour and Python types. The example at the end runs after the tour setup.

inbox

Lease pending deliveries assigned to this worker runtime.

inbox(self)

Parameter	Type and default	Usage

Returns: Array of Delivery with id, generation, kind and payload.

Permissions, lifecycle and errors: The lease is temporary. Process or durably hand off before Ack. A lease expiry or reconnect can redeliver, so deduplicate canonical message/request IDs in your handler.

Working Python example. Input/output fields are in the types reference.

ack

Acknowledge the delivery lease generation after safe handling.

ack(self, delivery: dict[str, Any])

Parameter	Type and default	Usage
delivery	dict[str, Any] (required)	Whole leased Delivery, including id and generation.

Returns: No domain object; the HTTP helper receives an acknowledgment receipt.

Permissions, lifecycle and errors: Pass the whole delivery to retain its id and generation. Stale lease acknowledgments conflict. Ack is not a request decision or proof of a business effect.

Working Python example. Input/output fields are in the types reference.

heartbeat

Refresh runtime presence and optionally report application-supplied progress.

heartbeat(self, **progress: Any)

Parameter	Type and default	Usage
**progress	keyword fields (default optional)	Explicit application-reported progress metadata; not automatic model telemetry.

Returns: No domain object; heartbeat acknowledgment.

Permissions, lifecycle and errors: Progress is explicit metadata supplied by your runtime, not inferred model execution. Heartbeat does not finish requests or acknowledge deliveries.

Working Python example. Input/output fields are in the types reference.

run

Run the SDK’s receive/handle/ack loop with long polling.

run(self, handler: Callable[[dict[str, Any]], None], stop: Callable[[], bool]=lambda: False)

Parameter	Type and default	Usage
handler	Callable[[dict[str, Any]], None] (required)	Required handler callback. Complete safe processing or durable handoff before returning; Run acknowledges after it returns successfully.
stop	Callable[[], bool] (default lambda: False)	Python callback checked between receive cycles; true stops after already handled deliveries are acknowledged.

Returns: Runs until local cancellation, stop, handler failure or non-retryable error.

Permissions, lifecycle and errors: Handler completion precedes Ack. Transient transport/5xx/429 failures retry; auth failures stop. Do not acknowledge before durable handoff. Stop controls are local, not request cancellation.

Working Python example. Input/output fields are in the types reference.

Example

Run this region after the shared setup. Assertions check the returned data; the full tour is a runnable program.

billing.heartbeat()
for delivery in billing.inbox():
    # A real worker stores or handles the delivery before acknowledging its lease.
    assert delivery['id'] and delivery['generation']
    billing.ack(delivery)
builder.send(target=target, body='A final worker event.')
processed = []
def handle(delivery):
    processed.append(delivery['id'])
billing.run(handle, stop=lambda: bool(processed))
assert processed

---

Read this page as Markdown