golem-call-from-external-scala

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.