Tools

A tool is a typed command that an agent calls through Golem, such as bash, npm install, tsc, or a tool you write. Tools are how an agent runs shell scripts, edits files, installs packages, compiles code, and fetches web pages, without a container or VM and without access to the agent’s memory.

Golem ships a set of built-in tools, and you can write your own in any Golem SDK.

How an agent loop uses tools

1. The agent loop lists the Golem tools bound to the agent, which the SDK exposes with their JSON schemas, and sends the schemas to the model together with the prompt.
2. The model answers with a tool call, such as npm install csv-parse.
3. The loop calls the tool through its generated client. Golem checks the agent’s permissions, runs any middleware, and runs the tool in a fresh sandbox on the agent’s filesystem.
4. The result goes back to the loop, which sends it to the model and continues.

With a framework such as the Vercel AI SDK, each Golem tool becomes one of the framework’s tools, whose execute function calls the Golem tool’s client. For example, in TypeScript with the Vercel AI SDK, inside an agent method:

// Excerpt: the Vercel AI SDK inside a Golem agent method
const result = await generateText({
  model: openai("gpt-4.1"),
  prompt: question,
  tools: {
    echo: tool({
      description: "Repeat a value",
      inputSchema: z.object({ value: z.string() }),
      execute: async ({ value }) => echoClient.echo({ value }),
    }),
  },
  stopWhen: stepCountIs(12),
});

The model calls are HTTP requests and the tool calls are Golem tool calls, so both are recorded in the agent’s oplog without any changes to the framework code. Files that tools write stay in the agent’s filesystem. The agent can serve them, for example as a web page, as described in Artifacts.

Open full-size image in a new tab.Open full-size image in a new tab.

How a tool call runs

Each call to a component tool runs in a fresh WebAssembly sandbox, created for that call and destroyed when it ends. The tool cannot read the calling agent’s memory, so code generated by a model and run through a tool cannot inspect or change the agent loop that launched it.

If the agent allows it, the tool works directly on the agent’s own filesystem. The agent can write a source file, run tsc on it, and read the compiled output, all on the same durable disk.

A tool call runs to completion and leaves nothing running: no process survives between calls, so a tool cannot keep a server running in the background. State that must last goes into files. The bash tool, for example, keeps only the working directory between calls. To make something an agent built available to users, serve it as an artifact: files from the agent’s filesystem, backed by endpoints on the agent.

Open full-size image in a new tab.Open full-size image in a new tab.

Tool calls are part of the agent’s durable execution. Every tool call executes exactly once: if a server fails in the middle of npm install, the agent recovers and the same tool call completes, without starting a second install. The tool records its external interactions, such as the packages it downloads, in the calling agent’s oplog. During recovery, Golem runs the tool’s code again against those recorded results, which rebuilds the files the tool wrote without downloading anything twice, and then the call continues where it stopped. A request that was still in flight when the server failed follows the same rules as any other outgoing HTTP request.

Built-in tools

Writing a tool

A tool is defined like a command-line program with types: commands, positional arguments, options and flags, input and output streams, a typed result, and declared errors. This tool has one command that takes a value and returns it:

import { ok, toolDefinition } from "@golemcloud/golem-ts-sdk";
import { z } from "zod";
 
export const echo = toolDefinition("echo")
  .version("1.0.0")
  .body((body) => body.positional("value", z.string()).returns(z.string()));
 
echo.implement({
  echo: async ({ value }) => ok(value),
});

import { Effect, Schema } from "effect";
import { Tool } from "@golemcloud/effect-golem";
 
export const echo = Tool.toolDefinition("echo", { version: "1.0.0" })
  .body((body) => body.positional("value", Schema.String).returns(Schema.String));
 
echo.implement({
  echo: ({ value }) => Effect.succeed(value),
});

use golem_rust::{tool_definition, tool_implementation};
 
#[tool_definition(version = "1.0.0")]
pub trait Echo {
    #[arg(value = "positional")]
    async fn echo(&self, value: String) -> String;
}
 
struct EchoImpl;
 
#[tool_implementation]
impl Echo for EchoImpl {
    async fn echo(&self, value: String) -> String {
        value
    }
}

import golem.runtime.annotations.{toolDefinition, toolImplementation}
 
@toolDefinition(name = "echo", version = "1.0.0")
trait Echo {
  def echo(value: String): String
}
 
@toolImplementation()
final class EchoImpl extends Echo {
  override def echo(value: String): String = value
}

#derive.tool("echo", version="1.0.0")
struct Echo {}
 
#derive.arg("value", scope="positional")
pub fn Echo::echo(value : String) -> String {
  value
}

import "github.com/golemcloud/golem/sdks/go/golem/tool"
 
type EchoTool struct{}
 
var Echo = tool.DefineTool[EchoTool]("echo", tool.Spec{Version: "1.0.0"})
 
type EchoArgs struct{ Value string }
 
var EchoBody = Echo.Body[EchoArgs, string](func(a *EchoArgs, s *tool.CommandSpec) {
	s.Positional(&a.Value)
})
 
var _ = EchoBody.Handle(func(_ *tool.Context, a EchoArgs) (string, error) {
	return a.Value, nil
})

Agent code calls a tool through its typed client. This is what an agent loop runs when the model chooses the tool:

import { toolClientDefinition } from "@golemcloud/golem-ts-sdk";
 
const client = toolClientDefinition(echo).client("echo");
const value = await client.echo({ value: "hello" });

import { Effect } from "effect";
import { Tool } from "@golemcloud/effect-golem";
 
const client = Tool.client(echo);
 
const program = Effect.gen(function* () {
  const value = yield* client({ value: "hello" });
});

let client = EchoClient::default();
let value = client.echo("hello".to_string()).await.unwrap();

val client = EchoClient()
val value: Future[Either[ToolError[Nothing], String]] = client.echo("hello")

let client = EchoClient::new()
defer client.drop()
let value = client.echo("hello").unwrap()

value, err := EchoBody.Call(func(a *EchoArgs) { a.Value = "hello" })
if err != nil {
	return "", err
}

A tool can be written in any Golem SDK language, and an agent can call tools written in any language. From one definition, Golem generates a typed client for each SDK, CLI help, a REST endpoint, and an MCP tool. Use a tool for stateless operations that should run in a fresh sandbox under the caller’s permissions; use an agent for something with its own identity and state.

Giving an agent a tool

An application declares the tools it uses, and an agent can only call tools that are bound to it in golem.yaml. The binding also decides what the tool may access on the agent’s behalf:

# golem.yaml (excerpt)
tools:
  bash: # the built-in bash tool, provisioned in every Golem installation
    release: { account: builtin-tool-owner@golem.cloud, name: bash, version: "0.2.1" }
agents:
  ReportAgent:
    tools:
      bash:
        filesystemAccess: allowed # the tool may use the agent's filesystem
        secretKeysRevealable: [] # the tool may not reveal any secret values

A binding can also list the configuration keys and secrets a tool may read (configKeysReadable, secretKeysReadable). A binding can only narrow access. The tool acts with the calling agent’s permissions, its permission cards, and a call succeeds only if the agent is both bound to the tool and permitted to use it.

Middleware

Middleware wraps tool calls and runs on every call. You configure it in golem.yaml, and Golem enforces it; agent code cannot list, remove, or bypass it. Typical middleware approves or rejects calls based on their arguments, waits for human approval before an irreversible action, redacts output, writes audit records, or enforces rate limits. Because middleware runs inside the durable agent, an approval step can wait hours for a person and survive restarts.

Choosing where code runs

Open full-size image in a new tab.Open full-size image in a new tab.

1. The agent’s own code handles logic, state, and model calls.
2. Golem tools handle shell scripts, files, Node.js, npm, TypeScript, and git. The work happens on the agent’s durable filesystem, and no separate machine has to stay running between calls.
3. A remote sandbox or VM handles native binaries, Python, system packages, Docker, real browsers, or GPUs. The agent calls it over HTTP or MCP, and its permissions must allow the connection. Golem records the calls and their results, but not the state of the remote machine.

MCP and sharing tools

• MCP import: tools from an existing MCP server can be bound and called like Golem tools, with typed clients. Each call runs on the upstream server; Golem records the call and its result in the agent’s oplog.
• MCP export: an application can expose its tools as an MCP server for other clients.
• Publishing: a tool can be published as a versioned release that other environments and accounts can use.
• From the CLI: golem tool invoke calls a tool as a given agent, and golem ssh opens a prompt where each line runs as a bash tool call under that agent’s permissions.

Next

Permissions: how Golem decides which tool calls and other operations an agent may perform.

Related guides:

• Tool authoring
• Tool security model
• Built-in tools in the application manifest
• MCP