Skip to main content
Sign In
Executing Code

Host Functions

Give untrusted code a narrow set of host-backed functions it calls as plain JavaScript. Credentials stay in your process.

Untrusted code should never hold your database password or API key. A host function runs in your process with your credentials, and the guest only sees its inputs and outputs. This is what makes Code Mode useful: the model writes one program that chains your tools.

Define host functions

Host functions are a record of collections, keyed by name. Each function needs only a Zod inputSchema and an execute handler; the keys name the collection and the function, and .describe() on the schema documents it for the model. Arguments from the guest are validated before your code runs.

hostFunctions is a VM option. Pass it on a call, or on createVm.

// Host functions run in your process, with your credentials. The guest only
// sees their inputs and outputs. The keys name the collection and the function,
// and `execute` receives the input its own schema describes.
const total = await evaluate<number>(generated, {
	hostFunctions: {
		orders: {
			list: {
				inputSchema: z
					.object({ customer: z.string() })
					.describe("List a customer's orders."),
				execute: ({ customer }) => [
					{ customer, amount: 40 },
					{ customer, amount: 2 },
				],
			},
		},
	},
	inputs: { customer: "customer_123" },
	timeoutMs: 5_000,
	output: { capture: "stderr" },
});
console.log(total.outcome === "succeeded" ? total.value : total.stderr); // 42

Call them from guest code

Inside the VM each collection is a global object and each function is async.

// Inside the VM each collection is a global, and each function is async. This
// is the code a model would write.
const generated = `(async () => {
	const list = await orders.list({ customer: inputs.customer });
	return list.reduce((sum, order) => sum + order.amount, 0);
})()`;
  • Keys round-trip: orderStore.listOrders in your options is orderStore.listOrders(input) in the guest and agentos-order-store list-orders on the CLI.
  • Each function takes one input object and resolves to what your execute returned. A schema violation, a thrown error, or a timeout rejects the promise.
  • The globals are frozen. A collection whose name is already a global, such as process, is not defined, and a warning is written to stderr.
  • The hostFunction permission scope gates which functions a guest may call. See permissions.

The same functions are also available to shell scripts and other languages as commands. Read the agentOS host functions reference for that, and for schemas, timeouts, and examples.

Edit this page