SDK Development
Developmentsdk-developmentSDK Development is an Agent Skill for development published in the golemcloud/golem repository on GitHub: a SKILL.md instruction file an AI agent can load to do this task.
Working on the Rust, TypeScript, or MoonBit SDKs in sdks/. Use when modifying SDK code, adding SDK features, or testing SDK changes with the main Golem platform.
How to use this skill
Bring this guide into your coding agent with a prompt tailored to the tool you use.
- Open your project in Codex.
- Copy and paste the prompt below.
- Review files and risks before approving any action.
Inspect the Agent Skill at https://github.com/golemcloud/golem/blob/HEAD/.agents/skills/sdk-development/SKILL.md and all supporting files. Report provenance, permissions, scripts, dependencies, and security risks. Propose an exact installation into .agents/skills/sdk-development, but wait for my approval before writing files or running scripts.
Copying this prompt does not install or run the skill. Review third-party files before use.
SDK Development
The SDKs in sdks/ are not part of the main build flow (cargo make build does not build them). Each SDK has its own build system and conventions.
Rust SDK (sdks/rust/)
Crates
golem-rust— Runtime API wrappers (transactions, durability, agentic framework, value conversions)golem-rust-macro— Procedural macros (#[derive(IntoValue)],#[agent_definition], etc.)
Building
cd sdks/rust
cargo build -p golem-rust
cargo build -p golem-rust-macro
Testing
Tests use test-r. Each test file must have test_r::enable!(); at the top.
cargo test -p golem-rust
cargo test -p golem-rust --features export_golem_agentic # Agent tests
Testing with the main platform
# From repository root
cargo make worker-executor-tests
Testing with golem-cli
Set GOLEM_RUST_PATH to use local SDK in generated applications:
export GOLEM_RUST_PATH=/path/to/golem/sdks/rust/golem-rust
golem-cli app new my-test-app
Code style
cargo fmt
cargo clippy
TypeScript SDK (sdks/ts/)
Prerequisites
- Node.js
- pnpm (managed via
packageManagerfield) wasm-rquickjs-cli:cargo install wasm-rquickjs-cli --version <VERSION>(checkWASM_RQUICKJS_VERSIONin.github/workflows/ci.yaml)cargo-componentv0.21.1 (exact version required for agent template builds)
Packages
Build order matters: golem-ts-types-core → golem-ts-typegen → golem-ts-sdk
Building
cd sdks/ts
npx pnpm install
npx pnpm run build
Testing
npx pnpm run test
cd packages/golem-ts-sdk && pnpm run test # Specific package
Agent template WASM
The agent template WASM embeds the SDK runtime. You must rebuild it when:
wasm-rquickjs-cliis updated- WIT dependencies change
- SDK runtime code changes (
baseAgent.ts,index.ts,resolvedAgent.ts)
cargo install cargo-component --version 0.21.1
npx pnpm run build-agent-template
Running pnpm run build alone is not sufficient — it only updates the JS bundle, not the pre-compiled WASM that TS components use.
Testing with the main platform
# From repository root
cargo make cli-integration-tests
Testing with golem-cli
export GOLEM_TS_PACKAGES_PATH=/path/to/golem/sdks/ts/packages
npx pnpm install && npx pnpm run build # Build first!
golem-cli app new my-test-app
Code style
npx pnpm run lint
npx pnpm run format
MoonBit SDK (sdks/moonbit/)
See sdks/moonbit/AGENTS.md for full details. The MoonBit SDK has its own build system (moon) and code generation tools (golem_sdk_tools).
Building
cd sdks/moonbit/golem_sdk
moon check --target wasm # Type-check
moon build --target wasm # Build
Testing
cd sdks/moonbit/golem_sdk
moon test # Run SDK tests
cd sdks/moonbit/golem_sdk_tools
moon test # Run code generation tool tests
Regenerating WIT bindings
cd sdks/moonbit/golem_sdk
wit-bindgen moonbit ./wit --derive-show --derive-eq --derive-error --project-name golemcloud/golem_sdk --ignore-stub
moon fmt
Code style
moon fmt
moon info # Regenerate .mbti interface files
Downstream Rebuild Requirements
SDK changes can require rebuilding test components. This is the most common source of errors.
Rust SDK change → test components
- Build
golem-rust/golem-rust-macro - Find Rust test components depending on the SDK: check
test-components/*/Cargo.tomlforgolem-rustreferences - Rebuild each affected component following its
AGENTS.md
TS SDK change → test components
- Build TS SDK packages (
npx pnpm run buildinsdks/ts/) - Rebuild agent template WASM (
npx pnpm run build-agent-templateinsdks/ts/) - Find TS test components depending on the SDK
- Rebuild each affected component following its
AGENTS.md
The agent template rebuild step is critical and easily forgotten.
WIT Dependencies
Both SDKs have WIT files synced from the root wit/ directory. Never manually edit wit/deps/ in either SDK.
# From repository root
cargo make wit
Checklist
- SDK code modified
- SDK builds successfully
- SDK tests pass
- Agent template rebuilt (if TS SDK runtime code changed)
- Dependent test components rebuilt (if any)
- Platform tests pass (
cargo make worker-executor-testsfor Rust SDK,cargo make cli-integration-testsfor TS SDK) - Code formatted and linted