# Golem Call From External Scala

> Golem Call From External Scala is an Agent Skill for development published in the golemcloud/golem repository on GitHub: a SKILL.md instruction file an AI agent can load to do this task.

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.

- Skill name: `golem-call-from-external-scala`
- Category: [Development](https://www.openparable.com/skill/development/1)
- Source: https://github.com/golemcloud/golem/blob/HEAD/golem-skills/skills/scala/golem-call-from-external-scala/SKILL.md
- Repository: golemcloud/golem (1,605 GitHub stars when collected)

## SKILL.md

# 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`:

```yaml
bridge:
  scala:
    external:
      agents: "*"
```

Or generate a bridge directly:

```shell
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.

```scala
// 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

```scala
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

```shell
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:

```yaml
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:

```scala
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:

```yaml
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.

---

Source: https://www.openparable.com/skill/development/golem-call-from-external-scala (OpenParable). Cite the canonical URL above.
