golem-add-agent-ts

name	golem-add-agent-ts
description	Adding a new TypeScript agent to a Golem component. Use when the user asks to create, add, or define a new agent type, implement an agent class, or add agent methods in a TypeScript Golem project.

Adding a New Agent to a TypeScript Golem Component

Overview

An agent is a durable, stateful unit of computation in Golem. Each agent type is a class decorated with @agent() that extends BaseAgent from @golemcloud/golem-ts-sdk.

Steps

1. Create the agent file — add a new file src/<agent-name>.ts
2. Define the agent class — decorate with @agent(), extend BaseAgent
3. Import from main.ts — add import './<agent-name>'; to src/main.ts
4. Build — run golem build to verify

src/main.ts is the entrypoint module that must import each agent module for side effects. Agent classes do not need to be exported for discovery — importing the module is sufficient because @agent() registers the class.

Agent Definition

import { BaseAgent, agent } from '@golemcloud/golem-ts-sdk';

@agent()
class CounterAgent extends BaseAgent {
    private readonly name: string;
    private value: number = 0;

    constructor(name: string) {
        super();
        this.name = name;
    }

    async increment(): Promise<number> {
        this.value += 1;
        return this.value;
    }

    async getCount(): Promise<number> {
        return this.value;
    }
}

Custom Types

Use TypeScript type aliases or interfaces for parameters and return types. Use named types instead of anonymous inline object types for better interoperability. TypeScript enums are not supported — use string literal unions instead:

type Coordinates = { lat: number; lon: number };
type WeatherReport = { temperature: number; description: string };
type Priority = "low" | "medium" | "high";

@agent()
class WeatherAgent extends BaseAgent {
    constructor(apiKey: string) {
        super();
    }

    async getWeather(coords: Coordinates): Promise<WeatherReport> {
        // ...
    }
}

Returning Failures

Agent methods should distinguish between domain errors (expected failure outcomes) and uncaught errors:

• Uncaught errors (thrown exceptions, rejected promises) are not returned to the caller as a failed invocation. Golem treats them as crashes: the invocation is retried according to the agent's retry policy, and if the retries are exhausted the agent itself becomes failed.
• Domain errors that the caller should observe as a normal failure result must be expressed in the method's return type using the SDK's Result<T, E> type.

import { BaseAgent, agent, Result } from '@golemcloud/golem-ts-sdk';

type WithdrawError =
    | { tag: 'insufficientFunds'; available: number }
    | { tag: 'accountClosed' };

@agent()
class Wallet extends BaseAgent {
    private readonly owner: string;
    private balance: number = 0;
    private closed: boolean = false;

    constructor(owner: string) {
        super();
        this.owner = owner;
    }

    async withdraw(amount: number): Promise<Result<number, WithdrawError>> {
        if (this.closed) {
            return Result.err({ tag: 'accountClosed' });
        }
        if (amount > this.balance) {
            return Result.err({ tag: 'insufficientFunds', available: this.balance });
        }
        this.balance -= amount;
        return Result.ok(this.balance);
    }
}

Returning Result.err(...) completes the invocation successfully — the caller receives the error as a value. Throwing (e.g. throw new Error(...)) or returning a rejected promise will instead trigger a retry and eventually fail the whole agent.

If the throw happens after a durable side effect has already completed, retry replays that side effect's recorded result. A common example is const response = await fetch(...); if (!response.ok) throw ...: the HTTP response status/body are recorded before the exception is thrown. Wrap the fetch, body read, and status check in atomically(...) when the exception should make Golem re-execute the HTTP request instead of replaying the recorded response.

Related Skills

• Load golem-js-runtime for details on the QuickJS runtime environment, available Web/Node.js APIs, and npm compatibility
• Load golem-file-io-ts for reading and writing files from agent code

Key Constraints

• All agent classes must extend BaseAgent and be decorated with @agent()
• Constructor parameters define agent identity — they must be serializable types
• TypeScript enums are not supported — use string literal unions instead
• Agents are created implicitly on first invocation — no separate creation step
• Invocations are processed sequentially in a single thread — no concurrency within a single agent
• The build pipeline uses golem-typegen for type metadata extraction; ensure experimentalDecorators and emitDecoratorMetadata are enabled in tsconfig.json