Tools

Expose your JavaScript functions to agents as CLI commands inside the VM.

• Define tools on the host with Zod input schemas
• Auto-generated CLI commands installed at /usr/local/bin/agentos-{toolkit}
• Code mode compatible for up to 80% token reduction since tool calls are just shell commands
• Tool list injected into the agent’s system prompt automatically

Getting started

Define a toolkit with Zod input schemas and pass it to agentOs(). Each tool becomes a CLI command inside the VM.

server.ts

server.ts

import { agentOs } from "rivetkit/agent-os";
import { setup } from "rivetkit";
import common from "@rivet-dev/agent-os-common";
import pi from "@rivet-dev/agent-os-pi";
import { toolKit, hostTool } from "@rivet-dev/agent-os-core";
import { z } from "zod";

const weatherToolkit = toolKit({
  name: "weather",
  description: "Weather data tools",
  tools: {
    forecast: hostTool({
      description: "Get the weather forecast for a city",
      inputSchema: z.object({
        city: z.string().describe("City name"),
        days: z.number().optional().describe("Number of days"),
      }),
      execute: async (input) => {
        const res = await fetch(`https://api.weather.example/forecast?city=${input.city}&days=${input.days ?? 3}`);
        return res.json();
      },
      examples: [
        { description: "3-day forecast for Paris", input: { city: "Paris", days: 3 } },
      ],
    }),
  },
});

const vm = agentOs({
  options: { software: [common, pi],
    toolKits: [weatherToolkit],
  },
});

export const registry = setup({ use: { vm } });
registry.start();

client.ts

client.ts

import { createClient } from "rivetkit/client";
import type { registry } from "./server";

const client = createClient<typeof registry>("http://localhost:6420");
const agent = client.vm.getOrCreate(["my-agent"]);

const session = await agent.createSession("pi", {
  env: { ANTHROPIC_API_KEY: process.env.ANTHROPIC_API_KEY! },
});
await agent.sendPrompt(session.sessionId, "What's the weather in Paris?");

Zod to CLI mapping

Zod schema fields are converted to CLI flags automatically. Field names are converted from camelCase to kebab-case.

Zod type	CLI syntax	Example
z.string()	--name value	--path /tmp/out.png
z.number()	--name 42	--limit 5
z.boolean()	--flag / --no-flag	--full-page
z.enum(["a","b"])	--name a	--format json
z.array(z.string())	--name a --name b	--tags foo --tags bar

Optional fields (via .optional()) become optional flags. Required fields are enforced at validation time.

What the agent sees

When toolkits are registered, CLI shims are installed at /usr/local/bin/agentos-{name} inside the VM and the tool list is injected into the agent’s system prompt.

The agent interacts with tools as shell commands:

# List all available toolkits
agentos list-tools

# List tools in a specific toolkit
agentos list-tools weather

# Get help for a tool
agentos-weather forecast --help

# Call a tool with flags
agentos-weather forecast --city Paris --days 3

# Call a tool with inline JSON
agentos-weather forecast --json '{"city":"Paris","days":3}'

# Call a tool with JSON from a file
agentos-weather forecast --json-file /tmp/input.json

On success, the tool exits 0 and writes a JSON envelope to stdout:

{"ok":true,"result":{"temperature":22,"condition":"sunny"}}

On failure (validation or execution error), the tool exits non-zero and writes the error message to stderr:

Missing required flag: --city

Tools vs MCP servers

agentOS supports two ways to give agents access to external functionality: host tools and MCP servers. Both work, but they have different tradeoffs.

	Host Tools	MCP Servers
How it works	Call JavaScript functions on the host directly	Connect to a standard MCP server
Authentication	None required. Direct binding to the agent’s OS.	Requires custom auth configuration per server
Code mode	Built-in. Tools are exposed as CLI commands, so agents can call them inside scripts for up to 80% token reduction.	Requires extra work to make code mode work out of the box
Latency	Near-zero. Bound directly to the host process.	Extra network hop to reach the MCP server
Setup	Define tools in your actor code with Zod schemas	Configure any standard MCP server

Use host tools when you want to expose your own JavaScript functions to agents. Use MCP servers when you want to connect to existing third-party services. See Sessions for MCP server configuration.

Security

Tool calls from the agent securely invoke your execute() functions on the host. Your functions run with full access to the host environment, so you can call databases, APIs, and services directly without proxying credentials into the VM. The agent never sees the credentials — it only sees the tool’s input/output contract.

Recommendations

• Keep tool descriptions concise. They are injected into the agent’s system prompt and consume tokens.
• Use .describe() on Zod fields to generate useful --help output.
• Set an explicit timeout (in ms) on long-running tools. Tools run without a timeout unless one is set.
• Tools execute on the host with full access to the host environment. Do not expose tools that could compromise the host without appropriate safeguards.