golem-call-from-external-scala

name	golem-call-from-external-scala
description	Calling Golem agents from external applications when the agent is written in Scala. Use when the user wants to invoke Scala agents from outside the Golem platform.

Calling Agents from External Applications (Scala)

Generate a Scala Bridge SDK

Golem can generate typed Scala bridge SDKs for calling agents from external JVM applications. The bridge target language is independent of the agent's source language: a Scala bridge can call agents written in Rust, TypeScript, Scala, or MoonBit.

Configure bridge generation in golem.yaml:

bridge:
  scala:
    external:
      agents: "*"

Or generate a bridge directly:

golem generate-bridge --language scala --agent-type-name MyAgent --output-dir scala-bridge

The generated output is a self-contained sbt project. For an agent type named CounterAgent, the client package is golem.bridge.client.counter_agent and the generated client object is CounterAgentClient.

Setup

Use the generated sbt project as a dependency from your external Scala application, or add your application entry point inside the generated project while prototyping.

// build.sbt
scalaVersion := "3.8.2"
name := "external-client"

lazy val bridge = RootProject(file("../scala-bridge/counter-agent-client"))

lazy val root = (project in file("."))
  .dependsOn(bridge)

Example

import golem.bridge.client.counter_agent.CounterAgentClient
import golem.bridge.runtime.GolemServer

import scala.concurrent.Await
import scala.concurrent.duration._

@main def main(): Unit =
  CounterAgentClient.configure(GolemServer.Local, "my-app", "local")

  val timeout = 30.seconds
  val counter = Await.result(CounterAgentClient.get("my-counter"), timeout)
  val result  = Await.result(counter.increment(), timeout)

  println(result)

Building and Running

sbt run

Authentication

• Local server: Use GolemServer.Local.
• Golem Cloud: Use GolemServer.Cloud(token) with your API token.
• Custom deployment: Use GolemServer.Custom(url, token).

Agent Constructors and Methods

Generated Scala bridge clients follow the same conventions as agent-to-agent RPC:

• Client.get(...) attaches to an existing agent instance.
• Client.getPhantom(...) attaches to an existing phantom instance.
• Client.newPhantom(...) creates a new phantom instance.
• Methods returning a result are exposed as Future[T].
• Fire-and-forget and scheduled methods return Future[Unit].

Generate Scala Internal Clients for Component-to-Component Calls

When one Golem component needs to call another agent or tool from Scala code, generate an internal Scala client instead of an external REST bridge:

bridge:
  scala:
    internal:
      agents:
        - CounterAgent
      tools:
        - echo
      outputDir: ./bridge-sdk/scala/internal   # Optional custom output directory

The internal mode generates client code that is linked into a Golem component. It does not generate a standalone JVM REST client, and it does not generate a component by itself.

Re-running golem build generates one Scala.js sbt project per selected internal dependency:

• agent clients use <agent-name>-guest-client/, for example counter-agent-guest-client/;
• tool clients use <tool-name>-tool-guest-client/, for example echo-tool-guest-client/.

With no custom outputDir, generated internal clients are written under golem-temp/bridge-sdk/scala/internal/. With outputDir, they are written directly under that directory.

Each generated internal client project is a Scala.js library. Its build.sbt enables ScalaJSPlugin, sets ModuleKind.ESModule, and depends on the Scala SDK artifacts:

libraryDependencies ++= Seq(
  "cloud.golem" %%% "golem-scala-core"  % "<golem-scala-version>",
  "cloud.golem" %%% "golem-scala-model" % "<golem-scala-version>"
)

Add the generated project as a dependency of the Scala component that performs the call, then import the generated client package from that component. Do not add agent_guest.wasm or extra linker settings to the generated internal client project; those belong to the consuming Scala component build/injection flow, while the client project itself is just a Scala.js library.

Internal clients use SDK-side types such as golem.schema.SchemaValue and golem.Datetime. Do not mix them with the external REST bridge runtime types under golem.bridge.runtime, which have a separate wire model.

Using a Generated TypeScript or Rust Bridge

You can also generate a TypeScript or Rust bridge SDK for agents written in Scala. The bridge target language is independent of the agent's source language:

bridge:
  ts:
    external:
      agents: "*"
  rust:
    external:
      agents: "*"

Then use the generated TypeScript or Rust client from your external application. See the golem-call-from-external-ts or golem-call-from-external-rust skills (available in TypeScript and Rust project templates) for details.