Introduction

I am writing a series of short posts showcasing the new features of Golem 1.5, to be released at the end of April, 2026. The episodes of this series will be short and assume the reader knows what Golem is. Check my other Golem-related posts for more information!

Parts released so far:

• Part 1: Code-first routes
• Part 2: Webhooks
• Part 3: MCP
• Part 4: Node.js compatibility
• Part 5: Scala support
• Part 6: User-defined snapshotting
• Part 7: Configuration and Secrets
• Part 8: Template simplifications and automatic updates
• Part 9: Agent skills
• Part 10: WebSocket client
• Part 11: Bridge libraries
• Part 12: REPL
• Part 13: Per-agent configuration

Components vs agents

Previously, in Golem components were the most important user-defined entities. Components were the unit of compilation, each transformed to be a WebAssembly component and all the customization such as environment variables, initial file system and so on were configurable per component.

In Golem 1.5 the primary entity is an agent. Agents are still organized into components - these are the unit of compilation and deployment, but each component can contain an arbitrary number of agents. These agents have to have unique type names in the whole application (that can consist of multiple components) so whenever we refer to a specific agent instance, for example to invoke them or query its metadata or oplog, we no longer need to deal with component ids like before. We can identify the agents just by their type name and constructor parameters.

To further continue our journey towards being agent first, in the new release all the customization is per agent. We can configure everything on the agent level:

• environment variables
• initial file system
• configuration
• bridge generation

With this small detail application manifests became much more in sync with how we can configure some other aspects (such as http routes and snapshotting) per agent from the code itself.

Example

The following example shows how we can configure different settings for three agents defined in the same component.

We start with the application's shared runtime settings. We define them as a component template so we can apply them to any component in our application, and every agent in those components will get them:

manifestVersion: "1.5.0"
app: supportdesk

componentTemplates:
  shared-runtime:
    env:
      RUST_LOG: info
      TZ: UTC
    files:
      - sourcePath: ./shared/ca-certificates.pem
        targetPath: /certs/ca-certificates.pem
        permissions: read-only
    presets:
      local:
        default: true
        env:
          GOLEM_ENV: local
      cloud:
        env:
          GOLEM_ENV: cloud

components:
  supportdesk:agents:
    dir: .
    templates: shared-runtime

Then we can provide additional configuration per agent. For InboxAgent we override the environment, config and initial file system:

agents:
  InboxAgent:
    env:
      OPENAI_API_KEY: "{{ OPENAI_API_KEY }}"
      MODEL: gpt-4.1-mini
    files:
      - sourcePath: ./prompts/inbox-system.md
        targetPath: /prompts/system.md
        permissions: read-only
      - sourcePath: ./data/routing-rules.json
        targetPath: /data/routing-rules.json
        permissions: read-only
    config:
      defaultQueue: general
      summarizeReplies: true
      classification:
        confidenceThreshold: 0.75
        labels:
          - billing
          - outage
          - product

We can define a completely different set of overrides for the other agents. Note that each agent has its own typed configuration, and we only have to satisfy each agent's own requirements.

agents:
  EscalationAgent:
    env:
      JIRA_BASE_URL: https://acme.atlassian.net
      JIRA_TOKEN: "{{ JIRA_TOKEN }}"
      MODEL: claude-3-7-sonnet
    files:
      - sourcePath: ./prompts/escalation-system.md
        targetPath: /prompts/system.md
        permissions: read-only
      - sourcePath: ./playbooks/p1-outage.md
        targetPath: /playbooks/p1-outage.md
        permissions: read-only
      - sourcePath: https://example.com/runbooks/severity-guide.md
        targetPath: /playbooks/severity-guide.md
        permissions: read-only
    config:
      projectKey: OPS
      defaultPriority: high
      pagerduty:
        serviceId: P123456
        autoPageAfterMinutes: 5

  AuditAgent:
    env:
      S3_BUCKET: supportdesk-audit
    files:
      - sourcePath: ./schemas/audit-event.schema.json
        targetPath: /schemas/audit-event.schema.json
        permissions: read-only
    config:
      redactFields:
        - email
        - phone
        - paymentToken
      retentionDays: 90

Finally, we can configure the bridge generator also per agent:

bridge:
  ts:
    agents:
      - InboxAgent
      - EscalationAgent
  rust:
    agents: AuditAgent

When we define our environments - these are the targets where we can deploy our application to - we can define componentPresets. This selects one section from the presets map we defined in the first snippet. This feature allows us to have different environment variables / configuration per deployment target!

environments:
  local:
    default: true
    server: local
    componentPresets: local
  prod:
    server: cloud
    componentPresets: cloud

As demonstrated, the Golem application manifest is very powerful and allows quite complicated setup, even though in its default form it is just a few lines long. To help working on these files, we are publishing a full JSON schema for it as well as a dedicated agent skill.