adrielc/helios-alpha/golem-add-component

Adding Components and Agent Templates to an Existing Golem Application

Both golem and golem-cli can be used — all commands below work with either binary.

Two Modes of golem new in an Existing Application

When golem new is run inside an existing application directory (one that already has a golem.yaml), it operates in existing application mode. There are two use cases:

1. Add a new component (with --component-name)

Creates a new component in the application. The component gets its own directory, source files, and entry in golem.yaml.

golem new --template <TEMPLATE> --component-name <NAMESPACE:NAME> --yes .

2. Add agent templates to an existing component (without --component-name)

Adds new agent template files to an existing component. The CLI automatically detects which component to target based on the template's language. If there are multiple components using the same language, specify --component-name to disambiguate.

golem new --template <TEMPLATE> --yes .

Template Names

Templates are specified as <language> (for the default template) or <language>/<name> (for named templates).

Rust templates

TypeScript templates

Scala templates

Required Flags

Optional Flags

Examples

Add a new Rust component to an existing application

golem new --template rust --component-name myapp:billing-service --yes .

This creates a new billing-service/ directory with Rust component scaffolding and adds a myapp:billing-service entry to golem.yaml.

Add a new TypeScript component alongside an existing Rust component

golem new --template ts --component-name myapp:frontend --yes .

Add the human-in-the-loop template to an existing Rust component

golem new --template rust/human-in-the-loop --yes .

When there is only one Rust component, the CLI automatically targets it.

Add a template to a specific component (multi-component app)

golem new --template rust/snapshotting --component-name myapp:orders --yes .

Single-Component to Multi-Component Promotion

When the existing application has a single component with dir: "." (source files in the root), adding a second component triggers an automatic layout migration:

1. The CLI creates a new subdirectory for the existing component (e.g., rust-main/)
2. It moves the existing component's source files into that subdirectory
3. It creates a new subdirectory for the new component
4. It updates golem.yaml to reflect the new directory layout

The CLI shows the planned file moves and asks for confirmation (auto-confirmed with --yes).

Agent Name Conflicts

Default templates all create an agent named CounterAgent. When adding a new component using a default template (e.g., rust, ts, scala), the generated agent will conflict with any existing CounterAgent in other components, causing deployment failures.

After adding a new component with a default template, rename the generated agent (both the type/trait name and the HTTP mount path in the source files) to something unique before building or deploying.

After Adding a Component or Template

1. Build to verify the new component compiles:

``shell golem build ``

1. Deploy to make it available:

``shell golem deploy --reset --yes ``

1. For cross-component communication, load the relevant RPC skill (golem-call-another-agent-rust, golem-call-another-agent-ts, or golem-call-another-agent-scala).