| name | golem-add-component |
| description | Adding a new component or agent templates to an existing Golem application. Use when adding a second component, adding agent templates like human-in-the-loop or snapshotting to an existing component, or converting a single-component app to multi-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
| Template | Description |
|---|
rust | Default — a simple counter agent |
rust/human-in-the-loop | Agent using promises for human-in-the-loop workflows |
rust/json | Agent demonstrating JSON API support |
rust/snapshotting | Agent with custom state snapshotting |
TypeScript templates
| Template | Description |
|---|
ts | Default — a simple counter agent |
ts/human-in-the-loop | Agent using promises for human-in-the-loop workflows |
ts/json | Agent demonstrating JSON API support |
ts/snapshotting | Agent with custom state snapshotting |
Scala templates
| Template | Description |
|---|
scala | Default — a simple counter agent |
Required Flags
| Flag | Description |
|---|
--template <TEMPLATE> | Template to apply (see template names above). |
--yes / -Y | Non-interactive mode. Always use this flag. |
Optional Flags
| Flag | Description |
|---|
--component-name <NAMESPACE:NAME> | Target component. Required when adding a new component. Also required when there are multiple existing components using the same language as the template. |
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:
- The CLI creates a new subdirectory for the existing component (e.g.,
rust-main/)
- It moves the existing component's source files into that subdirectory
- It creates a new subdirectory for the new component
- 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
-
Build to verify the new component compiles:
golem build --yes
-
Deploy to make it available:
golem deploy --reset --yes
-
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).
