#Golem SDK for MoonBit

#Overview

#Persistent permission derivation

#Host retry evaluation

#Self metadata and authority

#Quick Start

#0. Set up your project from the template

#moon.mod

• Change name from "golemcloud/golem_sdk_example1" to your module name (e.g. "myorg/my_app")
• Update description, repository, and other metadata fields

#golem.yaml

• Change app: from golem-sdk-example1 to your application name (e.g. my-app)
• Under components:, rename the component key from golem:moonbit-examples: to your component name (e.g. myorg:my-agent:)

#Component package directory

• Rename the golem_moonbit_examples/ directory to your component name in snake_case (e.g. my_agent/)
• The directory name must match the {{ component_name | to_snake_case }} value used in golem.yaml's build commands

#Agent source files

• Delete or modify the example agent files (counter.mbt, task_manager.mbt, multimodal_agent.mbt, rpc_example.mbt)
• The generated files (golem_reexports.mbt, golem_agents.mbt, golem_derive.mbt, golem_clients.mbt, golem_tools.mbt, golem_tool_clients.mbt, and golem_tool_middlewares.mbt) will be regenerated by golem build
• Add your own agents with #derive.agent structs
• Make sure you have an empty fn main {} somewhere in the package

#golem_moonbit_examples/moon.pkg (now your renamed directory)

• The import and link sections are auto-managed by the reexports codegen tool — no manual changes needed; they will be regenerated on first golem build

#1. Define an agent

///|
#derive.agent
struct Counter {
  name : String
  mut value : UInt64
}

///|
/// Creates a new counter with the given name
fn Counter::new(name : String) -> Counter {
  { name, value: 0, }
}

///|
/// Increments the counter
pub fn Counter::increment(self : Self) -> Unit {
  self.value += 1
}

///|
/// Returns the current value
pub fn Counter::get_value(self : Self) -> UInt64 {
  self.value
}

#2. Use custom data types

///|
#derive.golem_schema
pub(all) enum Priority {
  Low
  Medium
  High
} derive(Eq)

///|
#derive.golem_schema
pub(all) struct TaskInfo {
  title : String
  priority : Priority
  description : String?
}

#Unstructured text and binary

///|
pub(all) struct ReportMimeTypes {}

///|
impl @schema.AllowedMimeTypes for ReportMimeTypes with fn mime_types() {
  ["text/csv"]
}

///|
#derive.endpoint(get="/report")
pub fn ReportAgent::report(
  self : Self,
) -> Result[@schema.UnstructuredBinary[ReportMimeTypes]?, String] {
  Ok(Some(@schema.UnstructuredBinary::inline(self.csv, mime_type="text/csv")))
}

#3. Stream typed agent data

///|
fn stream_values(values : Array[UInt]) -> @schema.AgentStream[UInt] {
  @schema.AgentStream::produce(async fn(writer) {
    for value in values {
      match writer.write_one(value) {
        @schema.Accepted => ()
        @schema.PeerDropped => return
      }
    }
  })
}

///|
pub async fn Counter::sum(
  self : Self,
  input : @schema.AgentStream[UInt],
) -> UInt {
  let _ = self
  defer input.drop()
  let mut total = 0U
  for ;; {
    match input.read() {
      Some(value) => total += value
      None => return total
    }
  }
}

#4. Define an agent tool

///|
enum WeatherError {
  #derive.error(kind="usage-error", exit_code="2")
  UnknownCity(city~ : String)
}

///|
/// Look up current weather conditions.
#derive.tool("weather", version="1.0.0")
struct Weather {}

///|
#derive.arg("city", scope="positional", doc="city to query")
pub fn Weather::weather(city : String) -> Result[String, WeatherError] {
  if city == "" {
    Err(UnknownCity(city~))
  } else {
    Ok("Sunny")
  }
}

///|
#derive.arg("days", scope="option", short="d", min="1", max="10")
pub fn Weather::forecast(
  city : String,
  days : UInt?,
) -> Result[Array[String], WeatherError] {
  // ...
}

let client = WeatherClient::new()
let current : Result[String, @tool.ToolError[WeatherError]] =
  client.weather("London")
client.drop()

#Call a tool discovered at runtime

#5. Define a tool middleware component

///|
#derive.tool("messages")
struct Messages {}

///|
pub fn Messages::send(message : String) -> String {
  message
}

///|
#derive.tool_middleware("message-policy", presented="Messages")
struct MessagePolicy {}

///|
pub async fn MessagePolicy::send(
  underlying : MessagesUnderlying,
  message : String,
) -> Result[String, @toolMiddleware.ToolInvokeError[@tool.NoToolError]] {
  if message.contains("blocked") {
    // Zero underlying calls: this invocation is short-circuited.
    Err(
      @toolMiddleware.ToolInvokeError::ConstraintViolation(
        "messages containing 'blocked' are not allowed",
      ),
    )
  } else {
    // One underlying call: forward to the next inner layer.
    underlying.send(message)
  }
}

///|
fn main {

}

///|
#derive.universal_tool_middleware("audit")
pub async fn audit(
  invocation : @toolMiddleware.RawToolInvocation,
  underlying : @toolMiddleware.UnderlyingTool,
) -> Result[
  @toolMiddleware.RawInvocationResult,
  @toolMiddleware.ToolInvokeError[@toolMiddleware.RawTypedSchemaValue],
] {
  ignore(invocation.tool_name())
  ignore(invocation.tool_metadata())
  ignore(invocation.principal())
  underlying.invoke_raw(
    invocation.command_path(),
    invocation.input(),
    invocation.stdin(),
  )
}

import {
  "golemcloud/golem_sdk/tool-core" @tool,
  "golemcloud/golem_sdk/tool-middleware" @toolMiddleware,
}

supported_targets = "+wasm"

options(
  "is-main": true,
)

components:
  myorg:message-middlewares:
    templates: moonbit
    dir: message_middlewares

Tool middleware '<middleware>' references tool '<tool>' outside its package; GOL-34 supports same-package tool shapes only

///|
#derive.tool_middleware("file-adapter", presented="PublicFiles", expected="Storage")
struct FileAdapter {}

///|
pub async fn FileAdapter::read(
  underlying : StorageUnderlying,
  path : String,
) -> Result[String, @toolMiddleware.ToolInvokeError[@tool.NoToolError]] {
  underlying.fetch("files/" + path)
}

#6. Build and deploy

#Features

• Agent registry — register multiple agent types in a single component via #derive.agent
• HTTP routers — named ephemeral routers, incremental byte streams, immutable files, and OpenAPI providers; ordinary durable agents can expose live files
• Custom data types — #derive.golem_schema implements every nexessary trait to use custom data types on the public interface of your agents
• Agent-to-agent RPC — auto-generated client stubs (CounterClient); stream-bearing methods are awaited, while stream-free methods also support fire-and-forget and scheduled invocations
• Runtime reflection — discover agent types, pack reflected schemas, define caller-codec clients, or invoke direct SchemaValues
• Agent tools — code-first tool descriptors, command trees, constraints, custom errors, runtime dispatch, and typed tool RPC clients via #derive.tool
• Tool middleware — monomorphic policy/adapter middleware and universal transparent middleware with invocation-scoped underlying capabilities
• Multimodal input — accept mixed text, binary, and custom modality data via #derive.multimodal and @multimodal.Multimodal[T]
• Logging — structured logging via @logging.with_name("my-agent") with level filtering
• Tracing — span-based tracing via @context.with_span(...) with attributes
• Host API - exports Golem's host API
• Semantic retries — install policies in the host or interpret them around user code locally

#Local semantic retries

///|
let policy = try! @api.Policy::exponential(@api.Duration::millis(100), 2.0)
  .max_retries(4)
  .only_when(
    @api.Predicate::eq(@api.Props::error_type(), @api.Value::text("transient")),
  )
  .to_raw()

///|
let result = @api.retry_local(policy, () => call_remote_service(), properties=error => {
  [("error-type", @api.PredicateValue::Text(error.kind()))]
})

#Packages

#Code Generation

• golem_reexports.mbt — re-exports WASM entry points from the SDK
• golem_agents.mbt — agent registration, constructor deserialization, method dispatch
• golem_derive.mbt — serialization impls for #derive.golem_schema types
• golem_clients.mbt — RPC client stubs for agent-to-agent calls
• golem_tools.mbt — tool descriptors, custom error schemas, registration, and invocation dispatch
• golem_tool_clients.mbt — typed clients for invoking tools and nested subcommands
• golem_tool_middlewares.mbt — monomorphic/universal middleware adapters, descriptors, typed underlying wrappers, and registration

#Requirements

• MoonBit toolchain (moon)
• Golem CLI (golem) version 1.6.0+
• wasm-tools for component model linking
• golemcloud/golem_sdk_tools for code generation

#Documentation

• Golem Documentation
• MoonBit Documentation
• Example Project

#License