Tools
Reference for defineTool, httpTool, tool and the options a tool takes.
A tool is a function the model can call. defineTool runs your code in your worker, httpTool declares an endpoint the platform calls, and tool accepts the AI SDK's shape. Put the result in tools.
Import from @voicelayer/sdk.
defineTool
function · @voicelayer/sdk
defineTool<S extends ToolInputShape>(spec: { name, description, input, run, capability?, sendRealValues?, timeoutMs?, idempotent?, sequential? }): Record<string, ToolDefinition<S>>Define a tool whose code runs in your worker. It returns { [name]: tool }, so spread it into tools. The model sees description and input; run is your handler.
Parameters
| Name | Type | Required | Default | Description |
|---|---|---|---|---|
spec | object | yes | The tool's name, description, input and run function, plus optional settings. | |
spec.name | string | yes | The tool's name, used as its key in tools and shown to the model. | |
spec.description | string | yes | What the tool does and when to use it. The model reads this to decide whether to call it. | |
spec.input | S | yes | The arguments the model passes: an object of field names to 'string', 'number' or 'boolean', or a zod schema. | |
spec.run | (input: InferToolInput<S>, ctx: HandlerContext) => unknown | Promise<unknown> | yes | Your function, called with the validated input and the handler context. What it returns goes back to the model; a thrown error's message goes back too, so throw messages that are safe to say aloud. | |
spec.capability | string | no | `tool.<name>` | The capability the action checks require. |
spec.sendRealValues | boolean | no | false | Give run the caller's real values instead of placeholders; each release is recorded. |
spec.timeoutMs | number | no | 10000 | How long run may take, between 100 ms and 30 s. |
spec.idempotent | boolean | no | false | Mark the tool safe to repeat: after a lost or late reply the platform may run it once more. |
spec.sequential | boolean | no | false | Run this tool after the rest of a parallel batch of tool calls has finished. |
Returns
Record<string, ToolDefinition<S>>: An object keyed by the tool's name.
Example
tools: {
...defineTool({
name: 'lookup_order',
description: 'Find an order by its number.',
input: { orderId: 'string' },
run: async ({ orderId }, ctx) => {
await ctx.say('One moment.');
return { orderId, status: 'shipped' };
},
}),
}httpTool
function · @voicelayer/sdk
httpTool(spec: { name, description, input, url, method?, headers?, capability?, sendRealValues?, timeoutMs?, idempotent? }): Record<string, HttpToolDeclaration>Declare a tool that calls an HTTP endpoint fixed in the agent's definition. It is a declaration, not code: the platform makes the request. A {field} in the URL fills from the model's arguments. Headers are fixed text, and one that looks like a credential is refused at upload, so keep secrets in a vault connection. For a request body built by a function, write a defineTool that calls your endpoint instead.
Parameters
| Name | Type | Required | Default | Description |
|---|---|---|---|---|
spec | object | yes | The tool's name, description, input, URL and optional method, headers and settings. | |
spec.name | string | yes | The tool's name, used as its key in tools and shown to the model. | |
spec.description | string | yes | What the tool does and when to use it. | |
spec.input | ToolInputShape | yes | The arguments the model passes. | |
spec.url | string | yes | The endpoint to call. A {field} in the URL fills from the model's arguments. | |
spec.method | 'GET' | 'POST' | 'PUT' | 'PATCH' | 'DELETE' | no | 'POST' | The HTTP method. |
spec.headers | Readonly<Record<string, string>> | no | Fixed headers. One that looks like a credential is refused at upload. | |
spec.capability | string | no | `tool.<name>` | The capability the action checks require. |
spec.sendRealValues | boolean | no | false | Send the caller's real values instead of placeholders; each release is recorded. |
spec.timeoutMs | number | no | How long to wait for the endpoint, in milliseconds. | |
spec.idempotent | boolean | no | false | Mark the call safe to repeat after a lost or late reply. |
Returns
Record<string, HttpToolDeclaration>: An object keyed by the tool's name, to spread into tools.
Throws
- TypeError when
spec.bodyis a function orspec.allowPrivateNetworkis set; neither is supported.
Example
tools: {
...httpTool({
name: 'get_status',
description: 'Look up an order status.',
input: { orderId: 'string' },
url: 'https://api.acme.com/orders/{orderId}/status',
method: 'GET',
}),
}tool
function · @voicelayer/sdk
tool<S extends { readonly _output: unknown; }>(spec: ToolSpec<S>): AiSdkTool<InputOf<S>>
tool<S extends JsonSchemaOf>(spec: ToolSpec<S>): AiSdkTool<InputOf<S>>A tool in the AI SDK's shape, for an author who does not install ai: an identity function typed from the schema. A tool made by ai's own tool() is accepted in its place. inputSchema is a zod schema or the AI SDK's jsonSchema<T>(...).
Parameters
| Name | Type | Required | Description |
|---|---|---|---|
spec | ToolSpec<S> | yes | The tool's description, input schema and execute function. |
spec.description | string | yes | What the tool does and when to use it. |
spec.inputSchema | S | yes | A zod schema or jsonSchema(...) wrapper describing the arguments. |
spec.execute | (input: InputOf<S>, options: AiSdkToolOptions) => unknown | yes | Your function, called with the validated input and AI SDK options whose experimental_context is the handler context. |
spec.needsApproval | boolean | ((input: InputOf<S>, options: AiSdkToolOptions) => boolean | PromiseLike<boolean>) | no | Ask the person before running: true, or a function that decides per call (read as "always ask"). |
spec.approval | boolean | no | The same switch, under the name some AI SDK versions give it. |
Returns
AiSdkTool<InputOf<S>>: The same tool, typed.
Example
import { tool } from '@voicelayer/sdk';
import { z } from 'zod';
const lookup = tool({
description: 'Find an order by its number.',
inputSchema: z.object({ orderId: z.string() }),
execute: async ({ orderId }) => ({ orderId, status: 'shipped' }),
});ToolDefinition
interface · @voicelayer/sdk
interface ToolDefinition<S extends ToolInputShape = ToolInputShape>A tool the model can call, whose code runs in your worker. Put it in tools by name, or build it with defineTool.
Fields
| Name | Type | Required | Default | Description |
|---|---|---|---|---|
description | string | yes | What the tool does and when to use it. The model reads this to decide whether to call it. | |
input | S | yes | The arguments the model passes, as a shorthand object or a zod schema. | |
run | (input: InferToolInput<S>, ctx: HandlerContext) => unknown | Promise<unknown> | yes | Your function. The platform calls it after the action checks pass, within timeoutMs, and what it returns goes back to the model. A thrown error's message goes back too, as a failed tool result the model can apologise for, so throw messages that are safe to say aloud; the stack never leaves your worker. | |
capability | string | no | `tool.<name>` | The capability the action checks require. |
sendRealValues | boolean | no | false | Give this handler the caller's real values instead of placeholders; each release is recorded. |
timeoutMs | number | no | 10000 | How long run may take, between 100 ms and 30 s. |
idempotent | boolean | no | false | Mark the tool safe to repeat: after a lost or late reply the platform may run it once more on another session. |
sequential | boolean | no | false | Run this tool after the rest of a parallel batch of tool calls has finished. |
personApproves | PersonApprovesDeclaration | no | Ask a person on the team before this runs, on every transport. See PersonApprovesDeclaration. |
HttpToolDeclaration
interface · @voicelayer/sdk
interface HttpToolDeclarationA tool that calls an HTTP endpoint fixed in the agent's definition. Build one with httpTool.
Fields
| Name | Type | Required | Default | Description |
|---|---|---|---|---|
name | string | yes | The tool's name. | |
description | string | yes | What the tool does and when to use it. | |
input | ToolInputShape | yes | The arguments the model passes. | |
url | string | yes | The endpoint to call. A {field} in the URL fills from the model's arguments. | |
method | 'GET' | 'POST' | 'PUT' | 'PATCH' | 'DELETE' | yes | The HTTP method. | |
headers | Readonly<Record<string, string>> | no | Fixed headers. A header that looks like a credential is refused at upload; use a vault connection. | |
capability | string | no | `tool.<name>` | The capability the action checks require. |
sendRealValues | boolean | no | false | Send the caller's real values instead of placeholders; each release is recorded. |
timeoutMs | number | no | How long to wait for the endpoint, in milliseconds. | |
idempotent | boolean | no | false | Mark the call safe to repeat after a lost or late reply. |
ToolEntry
type · @voicelayer/sdk
type ToolEntry = ToolDefinition<ToolInputShape> | HttpToolDeclaration | AiSdkTool<never>A tool the model can call: a ToolDefinition, an httpTool declaration, or a tool in the AI SDK's shape such as tool({ inputSchema, execute }).
ToolInputShape
type · @voicelayer/sdk
type ToolInputShape = Readonly<Record<string, ShorthandPrimitive>> | z.ZodTypeAnyA tool's input: either an object of field names to 'string', 'number' or 'boolean' (for example { reason: 'string' }), or a zod schema. The runner validates the model's arguments against it before run and turns it into the JSON Schema the model sees.