Worker lifecycle

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

Inbox

Lease pending deliveries assigned to this worker runtime.

func (c *Client) Inbox(ctx context.Context) ([]Delivery, error)

Parameter	Type and default	Usage
ctx	context.Context (required)	Required Go context. Cancellation bounds this local call; it does not withdraw a durable request.

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 Go example. Input/output fields are in the types reference.

Ack

Acknowledge the delivery lease generation after safe handling.

func (c *Client) Ack(ctx context.Context, d Delivery) error

Parameter	Type and default	Usage
ctx	context.Context (required)	Required Go context. Cancellation bounds this local call; it does not withdraw a durable request.
d	Delivery (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 Go example. Input/output fields are in the types reference.

Heartbeat

Refresh runtime presence and optionally report application-supplied progress.

func (c *Client) Heartbeat(ctx context.Context, progress map[string]any) error

Parameter	Type and default	Usage
ctx	context.Context (required)	Required Go context. Cancellation bounds this local call; it does not withdraw a durable request.
progress	map[string]any (required)	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 Go example. Input/output fields are in the types reference.

Run

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

func (c *Client) Run(ctx context.Context, handler func(context.Context, Delivery) error) error

Parameter	Type and default	Usage
ctx	context.Context (required)	Required Go context. Cancellation bounds this local call; it does not withdraw a durable request.
handler	func(context.Context, Delivery) error (required)	Required handler callback. Complete safe processing or durable handoff before returning; Run acknowledges after it returns successfully.

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 Go 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.

if err := billing.Heartbeat(ctx, nil); err != nil {
  panic(err)
}
for _, delivery := range must(billing.Inbox(ctx)) {
  if err := billing.Ack(ctx, delivery); err != nil {
    panic(err)
  }
}
must(builder.Send(ctx, beepgrid.SendInput{Target: target, Body: "A final worker event."}, beepgrid.Key()))
workerCtx, cancelWorker := context.WithTimeout(ctx, 500*time.Millisecond)
processed := 0
err = billing.Run(workerCtx, func(_ context.Context, delivery beepgrid.Delivery) error {
  check(delivery.ID != "")
  processed++
  return nil
})
check(err != nil && workerCtx.Err() != nil && processed > 0)
cancelWorker()

---

Read this page as Markdown