Quickstart

This guide will get you up and running in Golem in minutes.

Install Golem CLI

Golem CLI is a command-line application that allows you to deploy components, create and invoke agents, and otherwise manage your Golem applications.

There are precompiled binaries of golem (and its other variants) for various platforms. Alternatively, you can build Golem CLI for yourself.

Precompiled binaries

There are precompiled binaries of two variants of the CLI here:

• golem is the full version of the command line interface, including a locally runnable version of Golem itself.
• golem-cli is a lightweight version of the command line interface, requiring a running Golem cluster

You can download the full version of golem from the following page:

In this documentation we will use the golem command in the snippets. The available commands (except the one for starting the local Golem cluster) are the same in both variants.

Running Golem

It is possible to test Golem locally without installing anything other than the golem executable described above. To use it, start the local Golem cluster by running the following command:

golem server run

To use the open source version of Golem in production, you will need to deploy it to your own infrastructure. See the deployment page for available deployment options.

It is also possible to use our hosted version of Golem, available at [https://console.golem.cloud (opens in a new tab)].

Building an Example

Golem runs components that are WebAssembly programs implementing agents. Every component defines one or more agent types, and Golem runs stateful, durable instances of these agent types that we call agents.

The golem command line interface provides a set of commands to create, build, and deploy components.

To get started, you create an application and a single component using one of the supported programming languages with the golem app new command. If no additional parameters are provided, the command will interactively ask for all required information.

golem app new
 
> Application name: agent-examples
> Select language for the new component TypeScript
> Select a template for the new component: default: The default agent template for TypeScript
> Component Package Name: example:counter
> Add another component or create application? Create application

This will generate a new component in a new directory named after the provided application name, and it is ready to be compiled and deployed to Golem.

To build the newly created component, use the following command:

golem app build

This compiles the newly created application, which consists of a single Golem component at the moment. An application can have multiple components, each implementing a different set of agent types. New components can be added to the application by using the golem component new command.

Write the code

import {
    BaseAgent,
    agent,
    prompt,
    description,
} 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;
    }
 
    @prompt("Increase the count by one")
    @description("Increases the count by one and returns the new value")
    async increment(): Promise<number> {
        this.value += 1;
        return this.value;
    }
}

In this simple example we define a very simple agent that is identified by a name string, and exposes a single agent method increment that increments the count by one and returns the new value. This is a simple example of an agent that does not communicate with other agents or external services, but has state.

Uploading Your Component

To upload your component to Golem, you can use the app deploy command.

golem app deploy

When you add a component you will see some basic information about the component such as its name, unique identifier, version, and size. In addition, you will see a list of exports. These are the exported agent types of the component.

Uploading a component to Golem does not actually execute the component. Instead, it only makes it available for execution in Golem.

Every separate running instance of your component is referred to as an agent, based on one of the agent types implemented by that component.

Create Agents

In Golem, every agent has a unique ID that has a specific format: it consists of the agent type followed by the values passed to the agent's constructor.

There are individual CLI commands to create agents and invoke agent methods, where this agent name is used to identify the agent.

For testing purposes, it is much easier to use the Golem REPL to create agents and interact with them.

First start the REPL using:

golem repl

The REPL uses a special scripting language called Rib. We can create some counter agents and interact with them using the following commands:

>>> let a1 = counter-agent("agent-1")
()
>>> let a2 = counter-agent("another")
()
>>> a1.increment()
1
>>> a1.increment()
2
>>> a2.increment()
1

Note that the REPL provides autocompletion on Tab.

Check the Invoke section to learn more about other ways to invoke agents.

Expose an HTTP API

Agents can be invoked from other agents, through the REPL or CLI, or Golem's Invocation API, but Golem Applications can also define HTTP APIs that map routes to agents and agent methods.

To finish the Quickstart example with an HTTP POST endpoint for tracking counts, let's open the golem.yaml file in the component's directory. It's going to contain a components and a dependencies section already.

To define the HTTP API, we add its definition and information about how to expose it:

httpApi:
  definitions:
    counter-api:
      version: '0.0.1'
      routes:
        - method: POST
          path: /{name}/increment
          binding:
            type: default
            componentName: "example:counter"
            response: |
              let name: string = request.path.name;
              let agent = counter-agent(name);
              let new-value = agent.increment();
              { status: 200, body: { result: "incremented ${name}, new value is ${new-value}" } }
 
  deployments:
    local:
    - host: localhost:9006
      definitions:
       - counter-api

Then use the golem CLI to deploy this API:

golem api deploy

After this command, the API is deployed to our locally running Golem instance and can be tried out by sending POST requests to http://localhost:9006/{name}/increment:

curl -X POST http://localhost:9006/agent-1/increment

Notes about the Golem 1.3 release

Read the following important notes about the Golem 1.3 release, especially if you have used previous Golem versions:

Next Steps

In this guide, you have learned how to build and deploy invincible serverless agents on Golem, and seen how you can interact with them as they execute.

Take your next steps with Golem by exploring the following resources:

• Read about the fundamentals of Golem
• Learn about the main concepts
• Read everything developing Golem applications
• Check out how to deploy Golem to your infrastructure
• Read the details of how to invoke workers
• Learn more about the Golem CLI
• Explore operational aspects such as how worker state is persisted, what metrics and logs are available
• Check the References section for detailed information on APIs and syntaxes