Basic Usage

Quick Start

The most common pattern: create a toolset and give your agent search and execute tools. The agent discovers and runs tools on demand.

import { StackOneToolSet } from "@stackone/ai";

// getTools returns the tool_search + tool_execute meta tools, so search must be
// enabled on the toolset (pass search: {} for defaults).
const toolset = new StackOneToolSet({ search: { method: "auto" } });

// Your agent gets 2 tools: tool_search + tool_execute
const tools = toolset.getTools({ accountIds: ["your-account-id"] });
const openaiTools = tools.toOpenAI();

Pass openaiTools to any OpenAI-compatible model and the agent will search for relevant tools, then execute them automatically. See the OpenAI integration guide for a full agent loop.

Fetch Tools

When you need specific tools instead of search and execute:

const tools = await toolset.fetchTools({ accountIds: ["your-account-id"] });
const openaiTools = tools.toOpenAI();

Filtering by provider, action, or pattern

// Filter by providers
const byProviders = await toolset.fetchTools({
  providers: ["hibob", "workday"],
  accountIds: ["your-account-id"],
});

// Filter by actions with exact match
const byActions = await toolset.fetchTools({
  actions: ["hibob_list_employees", "hibob_create_employees"],
  accountIds: ["your-account-id"],
});

// Filter by actions with glob patterns
const byGlob = await toolset.fetchTools({
  actions: ["*_list_*"],
  accountIds: ["your-account-id"],
});

// Combine multiple filters
const combined = await toolset.fetchTools({
  providers: ["hibob"],
  actions: ["*_list_*"],
  accountIds: ["your-account-id"],
});

See Tool Filtering for the full reference.

Multi-account usage

// Set accounts on the toolset for all subsequent calls
toolset.setAccounts(["account-123", "account-456"]);
const tools = await toolset.fetchTools();

// Or pass account IDs per request
const toolsDirect = await toolset.fetchTools({
  accountIds: ["account-123", "account-456"],
});

// Loop over customer accounts dynamically
const customerAccounts = ["account-1", "account-2", "account-3"];

for (const accountId of customerAccounts) {
  const tools = await toolset.fetchTools({
    actions: ["workday_list_workers"],
    accountIds: [accountId],
  });
  const employeeTool = tools.getTool("workday_list_workers");
  if (employeeTool) {
    const employees = await employeeTool.execute({});
    console.log(`Found employees for ${accountId}`);
  }
}

Tool Execution

Direct tool execution (for debugging)

Direct execution is useful for testing and debugging. In production, your agent framework handles tool calls automatically.

const tools = await toolset.fetchTools({ accountIds: ["your-account-id"] });
const employeeTool = tools.getTool("workday_list_workers");

if (employeeTool) {
  const result = await employeeTool.execute({
    query: { limit: 10 },
  });
  console.log(result);
}

File downloads (binary responses)

Actions that download a file (for example googledrive_unified_download_file, documents_download_file, or any *_unified_download_file) return raw bytes plus metadata, not parsed JSON. The SDK decides from the response Content-Type: JSON is parsed as usual, and anything else is treated as a file download. Because execute() is typed to return a JSON object, use the exported isBinaryDownloadResult guard to narrow the result to the file shape.

import { writeFileSync } from "node:fs";
import { isBinaryDownloadResult } from "@stackone/ai";

const tools = await toolset.fetchTools({
  actions: ["googledrive_*"],
  accountIds: ["your-account-id"],
});
const download = tools.getTool("googledrive_unified_download_file");

if (download) {
  const result = await download.execute({ id: "file-id" });

  // isBinaryDownloadResult narrows result so content is a Buffer (no cast) and
  // confirms this was a file download rather than a JSON response.
  if (isBinaryDownloadResult(result)) {
    writeFileSync(result.fileName ?? "download.bin", result.content);
  }
}

The narrowed result describes the file:

Key	Type	Description
`content`	`Buffer`	Raw file bytes. Not JSON-serializable (see note).
`contentType`	`string`	File MIME type (for example `application/pdf`), or `application/octet-stream`.
`statusCode`	`number`	HTTP status of the download response.
`headers`	`object`	Response headers.
`fileName`	`string \| null`	Filename from `Content-Disposition` (RFC 5987 `filename*` aware), else `null`.

content is a Buffer and is not JSON-serializable. If you forward tool results to an LLM (or anything that re-serializes to JSON), handle or strip the content key. For example, base64-encode it on the LLM-facing path.

Environment Configuration

export STACKONE_API_KEY=your_api_key

Account IDs are passed per-request when fetching tools or via getTools({ accountIds: [...] }).

Next Steps

OpenAI Integration for building agents with function calling
Vercel AI SDK for streaming workflows
Tool Search for natural language tool discovery
Tool Filtering for advanced filtering patterns

Overview

Getting Started

Frameworks

API Behavior

Quick Start

Fetch Tools

Tool Execution

Environment Configuration

Next Steps

​Quick Start

​Fetch Tools

​Tool Execution

​Environment Configuration

​Next Steps

Quick Start

Fetch Tools

Tool Execution

Environment Configuration

Next Steps