golem-call-from-external-rust

name	golem-call-from-external-rust
description	Calling Golem agents from external Rust applications using generated bridge SDKs. Use when the user wants to invoke agents from outside the Golem platform, from a Rust CLI, server, or any native Rust application.

Calling Agents from External Rust Applications

Overview

Golem can generate typed Rust client libraries (bridge SDKs) for calling agents from any external Rust application — a CLI tool, a web server, a background job, etc. The generated client communicates with the Golem server's REST API and provides a fully typed interface matching the agent's methods.

Step 1: Enable Bridge Generation

Add a bridge section to golem.yaml:

bridge:
  rust:
    external:
      agents: "*"                    # Generate for all agents
      # Or list specific agents:
      # agents:
      #   - MyAgent
      #   - my-app:billing
      outputDir: ./bridge-sdk/rust   # Optional custom output directory

The agents field accepts "*" (all agents), or a list of agent type names or component names (namespace:name).

Step 2: Generate the Bridge SDK

The recommended approach is to declare the bridge in golem.yaml (as shown above) and let golem build produce the SDK as part of the normal build:

golem build --yes

This produces a Rust crate per agent type (e.g., my-agent-client/) in the configured output directory (or golem-temp/bridge-sdk/rust/ by default). Re-running golem build after agent changes keeps the generated client in sync automatically.

Avoid invoking golem generate-bridge manually — it exists as a low-level escape hatch, but the manifest-driven flow above is the supported way to keep bridges configured, reproducible, and up to date.

Step 3: Use the Generated Client

Add the generated crate as a path dependency in your external Rust project's Cargo.toml:

[dependencies]
my-agent-client = { path = "../path/to/bridge-sdk/rust/my-agent-client" }

Then use the generated client:

use my_agent_client::{GolemServer, MyAgent};

#[tokio::main]
async fn main() -> Result<(), Box<dyn std::error::Error>> {
    // Configure the Golem server connection
    my_agent_client::configure(GolemServer::Local, "my-app", "local");

    // Get or create an agent instance
    let agent = MyAgent::get("my-instance".to_string()).await?;

    // Call methods — fully typed parameters and return values
    let result = agent.do_something("input".to_string()).await?;
    println!("Result: {:?}", result);

    Ok(())
}

Server Configuration

The GolemServer enum supports three modes:

// Local development server (http://localhost:9881)
GolemServer::Local

// Golem Cloud
GolemServer::Cloud { token: "your-api-token".to_string() }

// Custom deployment
GolemServer::Custom {
    url: "https://my-golem.example.com".parse()?,
    token: "your-token".to_string(),
}

Phantom Agents

To create multiple agent instances with the same constructor parameters, use phantom agents:

let agent = MyAgent::get_phantom(uuid::Uuid::new_v4(), "shared-name".to_string()).await?;

Or generate a random phantom ID automatically:

let agent = MyAgent::new_phantom("shared-name".to_string()).await?;

Agent Configuration

If the agent has local configuration fields, use the _with_config variants:

let agent = MyAgent::get_with_config(
    "my-instance".to_string(),
    Some(my_config_value),    // config parameter (Option)
).await?;

Generated Crate Dependencies

The generated crate depends on golem-client, golem-common, golem-wasm, reqwest, serde_json, uuid, and chrono. These are resolved from crates.io or from the Golem repository depending on the SDK version.

Key Points

• Bridge generation runs during golem build — agents must be built first so their type information is available
• The generated code is fully typed — method parameters and return types match the agent definition
• All custom types (records, variants, enums, flags) are generated as corresponding Rust types
• The client uses async/await with reqwest for HTTP communication
• Each agent type gets its own crate with a Cargo.toml and src/lib.rs