golem-call-from-external-rust

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