Defining Golem Components

Creating a project

Golem's command line interface provides a set of predefined, Golem-specific templates to choose from as a starting point.

golem app new my-app ts
cd my-app

An application can consist of multiple components. Add a new component by choosing from one of the available templates. To see the list of available templates, run:

golem component new

Then create a new component using the chosen template:

golem component new ts my:component

Defining agents

Defining Golem agents is done using the Golem SDK, which is included in all the templates provided by golem.

import {
    BaseAgent,
    agent,
    description,
    prompt
} from '@golemcloud/golem-ts-sdk';
 
@agent
class MyAgent extends BaseAgent {
    // ...
}

A component must define at least one agent, but can also define multiple ones.

Agent constructors

Every agent must define a constructor with an arbitrary number of parameters. These parameters form the agent identifier. Every possible parameter value combination identifies a particular agent instance.

For example, an agent working on a particular user's particular request could be defined as:

@agent()
class RequestHandler extends BaseAgent {
    private readonly userId: string;
    private readonly requestId: string;
 
    constructor(userId: string, requestId: string) {
        super();
        this.userId = userId;
        this.requestId = requestId;
    }
}

An agent with a constructor like this can be identified by request-handler("user-123", "request-456").

Agent methods

Every public method of an agent class is an agent method, which can be called by other remote agents, externally through Golem's invocation API, and can also be mapped to HTTP APIs.

Agent methods can (and should) be also annotated with the @prompt and @description decorators:

• prompt should provide information for an external AI to understand what needs to be passed to the method as parameters
• description should be a human-readable description of what the method does

This metadata is stored in the Golem component and can be used when exposing the agents through MCP, for example.

The following example shows the use of the decorators on a simple agent method:

@agent()
type TaskDetails = // ...;
type RequestHandlerStatus = // ...;
 
class RequestHandler extends BaseAgent {
    // ...
 
    @prompt("Enter new details about the task")
    @description("Adds some more details to the request handler about the task being performed. The result is an update of the current status.")
   async addDetails(details: TaskDetails): Promise<RequestHandlerStatus> {
       // ...
   }
}

Supported data types

The SDK supports a large variety of data types to be used in agent constructors and agent methods, both in parameter and return type position. When a type is not supported, it will report an error at compile time.

Check the page about data type mapping to learn how each type is mapped to Rib (when calling the agent methods from the API gateway or the REPL) and JSON (when using the invocation API).

Worker configuration

It is often required to pass configuration values to agents when they are started.

In general Golem supports three different ways of doing this:

1. Defining a list of string arguments passed to the agent, available as command line arguments
2. Defining a list of key-value pairs passed to the agent, available as environment variables.
3. Defining dedicated configuration key-value pairs (experimental).

Command line arguments and environment variables

import { argv, env } from "node:process";

Environment variables can be specified when an agent is explicitly created, but there are some environment variables that are always set by Golem:

• GOLEM_AGENT_ID - the ID of the agent
• GOLEM_AGENT_TYPE - the agent type (first part of the agent ID)
• GOLEM_COMPONENT_ID - the ID of the agent's component
• GOLEM_COMPONENT_VERSION - the version of the component used for this agent

In addition to these, when using Agent to Agent communication, agents created by remote calls inherit the environment variables of the caller.

This feature makes environment variables a good fit for passing configuration such as hostnames, ports, or access tokens to trees of agents.

Default environment variables

It is possible to define default environment values and config key-value pairs for a component using the app manifest. These values are automatically set for each agent created from the component, but can be overridden when creating the agent.

To set component level environment variables, use the env section of the golem.yaml:

components:
    my:component:
        env:
            MY_ENV_VAR: "some value"
            ANOTHER_ENV_VAR: "another value"