Golem Call From External TS

Calling Agents from External TypeScript Applications

Overview

Golem can generate typed TypeScript client libraries (bridge SDKs) for calling agents from any external Node.js or TypeScript application — a web server, a CLI tool, a serverless function, 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:
  ts:
    external:
      agents: "*"                    # Generate for all agents
      # Or list specific agents:
      # agents:
      #   - MyAgent
      #   - my-app:billing
      outputDir: ./bridge-sdk/ts     # 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 an npm package per agent type (e.g., my-agent-client/) in the configured output directory (or golem-temp/bridge-sdk/ts/ 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: Install and Build the Generated Package

In the generated package directory:

cd bridge-sdk/ts/my-agent-client
npm install
npm run build

Then add it as a dependency in your external TypeScript project:

{
  "dependencies": {
    "my-agent-client": "file:../path/to/bridge-sdk/ts/my-agent-client"
  }
}

Step 4: Use the Generated Client

import { MyAgent, globalConfig } from 'my-agent-client';

// Configure the Golem server connection
globalConfig({
  server: { type: 'local' },
  application: 'my-app',
  environment: 'local',
});

// Get or create an agent instance
const agent = await MyAgent.get('my-instance');

// Call methods — fully typed parameters and return values
const result = await agent.doSomething('input');
console.log('Result:', result);

Server Configuration

The server field supports three modes:

// Local development server (http://localhost:9881)
{ type: 'local' }

// Golem Cloud
{ type: 'cloud', token: 'your-api-token' }

// Custom deployment
{ type: 'custom', url: 'https://my-golem.example.com', token: 'your-token' }

Phantom Agents

To create multiple agent instances that share the same identity (id) field values, use phantom agents:

import { v4 as uuidv4 } from 'uuid';

const agent = await MyAgent.getPhantom(uuidv4(), 'shared-name');

Or generate a random phantom ID automatically:

const agent = await MyAgent.newPhantom('shared-name');

Agent Configuration

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

const agent = await MyAgent.getWithConfig(
  'my-instance',
  someConfigValue,    // config parameter (optional)
);

Generated Package Dependencies

The generated npm package depends on @golemcloud/golem-ts-bridge (the shared bridge runtime) and uuid. It is built with TypeScript and outputs ES module format with type declarations.

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 TypeScript types
• The client uses fetch for HTTP communication
• Each agent type gets its own npm package with package.json, tsconfig.json, and a .ts source file
• Run npm install && npm run build in the generated package before using it