Core Concepts

Tools & Toolsets

View as Markdown

Tools describe callable capabilities that hosted agents can use. Toolsets group tools and built-ins so an invocation receives the right capability set.

Use tools and toolsets with invocations. They are not needed when you connect an external CDP client such as Playwright or Puppeteer.

Create a tool

1const tool = await space.tools.create({
2  name: "lookup_customer",
3  description: "Look up a customer record by email.",
4  inputSchema: {
5    type: "object",
6    properties: {
7      email: { type: "string" },
8    },
9    required: ["email"],
10  },
11  outputSchema: {
12    type: "object",
13    properties: {
14      customerId: { type: "string" },
15    },
16  },
17  execution: {
18    type: "webhook",
19    url: "https://example.com/tools/lookup-customer",
20    auth: { type: "none" },
21  },
22});

Create a toolset

1const toolset = await space.toolsets.create({
2  name: "crm-tools",
3  customToolIds: [tool.id],
4  builtin: {
5    storage: true,
6    artifacts: true,
7  },
8});

Use a toolset in an invocation

1await runtime.invocations.create({
2  provider: "stagehand",
3  operation: "agent.execute",
4  toolsetId: toolset.id,
5  input: {
6    instruction: "Find the account owner for [email protected].",
7  },
8});

Inspect tool calls

1const { toolCalls } = await space.toolCalls.list({
2  toolId: tool.id,
3  limit: 20,
4});