Waiting for External Input with Golem Promises (Rust)

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 in the golem_rust crate:

Function	Signature	Description
`create_promise`	`fn create_promise() -> PromiseId`	Creates a new promise and returns its ID
`blocking_await_promise`	`fn blocking_await_promise(id: &PromiseId) -> Vec<u8>`	Blocks until the promise is completed (sync)
`await_promise`	`async fn await_promise(id: &PromiseId) -> Vec<u8>`	Awaits promise completion (async)
`complete_promise`	`fn complete_promise(id: &PromiseId, data: &[u8]) -> bool`	Completes a promise with raw bytes

JSON Helpers

For structured data, use the JSON wrappers from golem_rust::json:

Function	Signature
`blocking_await_promise_json<T: DeserializeOwned>`	`fn(id: &PromiseId) -> Result<T, serde_json::Error>`
`await_promise_json<T: DeserializeOwned>`	`async fn(id: &PromiseId) -> Result<T, serde_json::Error>`
`complete_promise_json<T: Serialize>`	`fn(id: &PromiseId, value: T) -> Result<bool, serde_json::Error>`

Imports


use golem_rust::{create_promise, complete_promise, blocking_await_promise, await_promise, PromiseId};
// For JSON helpers:
use golem_rust::json::{await_promise_json, blocking_await_promise_json, complete_promise_json};

Usage Pattern

1. Create a Promise and Wait (Sync)


let promise_id = create_promise();
// Pass promise_id to an external system...
let data: Vec<u8> = blocking_await_promise(&promise_id);

2. Create a Promise and Wait (Async)


let promise_id = create_promise();
// Pass promise_id to an external system...
let data: Vec<u8> = await_promise(&promise_id).await;

3. Complete a Promise from Another Agent


complete_promise(&promise_id, b"done");
// Or with JSON:
complete_promise_json(&promise_id, MyResponse { status: "approved".into() }).unwrap();

PromiseId Structure

A PromiseId contains an agent_id and an oplog_idx. 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


use golem_rust::{
    agent_definition, agent_implementation, endpoint,
    create_promise, PromiseId,
};
use golem_rust::json::await_promise_json;
use serde::{Deserialize, Serialize};
 
#[derive(Serialize, Deserialize, PartialEq)]
enum Decision {
    Approved,
    Rejected,
}
 
#[agent_definition(mount = "/workflows")]
pub trait WorkflowAgent {
    fn new(name: String) -> Self;
 
    async fn start_approval(&mut self) -> String;
}
 
struct WorkflowAgentImpl {
    name: String,
}
 
#[agent_implementation]
impl WorkflowAgent for WorkflowAgentImpl {
    fn new(name: String) -> Self {
        Self { name }
    }
 
    #[endpoint(post = "/approve")]
    async fn start_approval(&mut self) -> String {
        // 1. Create a promise
        let promise_id = create_promise();
 
        // 2. Pass promise_id.oplog_idx to an external system (e.g. via RPC, HTTP, etc.)
        // The agent is now durably suspended.
 
        // 3. Wait for external completion
        let decision: Decision = await_promise_json(&promise_id)
            .await
            .expect("Invalid payload");
 
        if decision == Decision::Approved {
            format!("Workflow {} approved ✅", self.name)
        } else {
            format!("Workflow {} rejected ❌", self.name)
        }
    }
}

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