Waiting for External Input with Golem Promises (Scala)

Overview

A Golem promise lets an agent suspend its execution until an external event completes it. The agent creates a promise, passes the promise ID to an external system (another agent, a webhook, a UI, an HTTP API call), and then awaits the result. The Golem runtime durably suspends the agent — consuming no resources — until the promise is fulfilled.

API

All functions are on the golem.HostApi object:

Method	Signature	Description
createPromise	(): PromiseId	Creates a new promise and returns its ID
awaitPromiseBlocking	(id: PromiseId): Array[Byte]	Blocks until the promise is completed (sync)
awaitPromise	(id: PromiseId): Future[Array[Byte]]	Awaits promise completion (async Future)
completePromise	(id: PromiseId, data: Array[Byte]): Boolean	Completes a promise with raw bytes

JSON Helpers (Schema-based)

For structured data, use the JSON variants which require an implicit zio.blocks.schema.Schema[A]:

Method	Signature
awaitPromiseBlockingJson[A]	(id: PromiseId)(implicit Schema[A]): A
awaitPromiseJson[A]	(id: PromiseId)(implicit Schema[A]): Future[A]
completePromiseJson[A]	(id: PromiseId, value: A)(implicit Schema[A]): Boolean

Imports

import golem.HostApi
import golem.HostApi.PromiseId

Usage Pattern

1. Create a Promise and Wait (Blocking)

val promiseId = HostApi.createPromise()
// Pass promiseId to an external system...

// Agent is durably suspended here until the promise is completed
val data: Array[Byte] = HostApi.awaitPromiseBlocking(promiseId)

2. Create a Promise and Wait with JSON Decoding

case class Decision(status: String) derives Schema

val promiseId = HostApi.createPromise()
val decision: Decision = HostApi.awaitPromiseBlockingJson[Decision](promiseId)

3. Complete a Promise from Another Agent

HostApi.completePromise(promiseId, "approved".getBytes)
// Or with JSON:
HostApi.completePromiseJson(promiseId, Decision("approved"))

PromiseId Structure

A PromiseId contains an agentId and an oplogIdx. To let an external system complete the promise via the Golem REST API, the agent must expose both fields. The external caller then sends:

POST /v1/components/{component_id}/workers/{agent_name}/complete
Content-Type: application/json

{"oplogIdx": <oplog_idx>, "data": [<bytes>]}

Full Example: Human-in-the-Loop Approval

import golem.*
import zio.blocks.schema.Schema

case class Decision(status: String) derives Schema

@agentDefinition
trait WorkflowAgent extends BaseAgent {
  class Id(name: String)

  def startApproval(): String
}

@agentImplementation()
class WorkflowAgentImpl extends WorkflowAgent {
  private var name: String = ""

  override def init(id: Id): Unit = {
    name = id.name
  }

  override def startApproval(): String = {
    // 1. Create a promise
    val promiseId = HostApi.createPromise()

    // 2. Pass promiseId.oplogIdx to an external system
    // The agent is now durably suspended.

    // 3. Wait for external completion
    val decision = HostApi.awaitPromiseBlockingJson[Decision](promiseId)

    if (decision.status == "approved")
      s"Workflow $name approved ✅"
    else
      s"Workflow $name rejected ❌"
  }
}

Use Cases

• Human-in-the-loop: Pause a workflow until a human approves or rejects
• Webhook callbacks: Wait for an external HTTP callback to arrive
• Inter-agent synchronization: One agent creates a promise, another completes it
• External event ingestion: Suspend until an IoT sensor, payment gateway, or third-party API sends a signal