Vercel AI SDK

StackOne tools work with Vercel AI SDK to build AI applications using React, Next.js, and other frameworks.

Supported languages: TypeScript.

Streaming responses with real-time tool execution
React hooks for building AI UIs
Multi-step tool calls with automatic handling
Framework compatibility with Next.js, React, Vue, and more

Calling actions

Install

# Requires Node.js 16.0 or higher
# TypeScript 4.5 or higher (recommended)

# Using npm
npm install @stackone/ai ai @ai-sdk/openai

# Using pnpm
pnpm add @stackone/ai ai @ai-sdk/openai

# Using yarn
yarn add @stackone/ai ai @ai-sdk/openai

# Using bun
bun add @stackone/ai ai @ai-sdk/openai

export STACKONE_API_KEY=your_api_key_here

Fetch Tools

Two approaches to retrieving tools:

Fetch Tools (with filtering) — fetch all tools upfront with optional filters applied.
Search & Execute — hand the model just tool_search + tool_execute and let the agent discover what it needs at runtime.

See Tool Discovery for more details on which may be best in your scenario.

Fetch tools
Search & execute

By default this fetches every tool enabled for the account. Narrow it by passing providers (specific connectors) or actions — exact names or glob patterns (e.g. workday_*, or *_list_* for read-only tools).

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

// Get account ID from your app's auth context or StackOne dashboard
const accountId = 'your-account-id';

const toolset = new StackOneToolSet();

// Fetch tools dynamically for this account.
// Optionally narrow the fetch with filters:
//   providers: ["hibob", "workday"]    — only these connectors
//   actions: ["*_list_*", "*_get_*"]   — glob patterns, e.g. read-only actions
const tools = await toolset.fetchTools({
  accountIds: [accountId]
});

// Convert to Vercel AI SDK format
const aiSdkTools = await tools.toAISDK();

The LLM receives only 2 tools and searches the catalog autonomously:

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

const toolset = new StackOneToolSet({
  search: { method: 'semantic', topK: 3 },
});

// tools contains only tool_search + tool_execute
const tools = toolset.getTools({ accountIds: ['your-account-id'] });

// Convert to Vercel AI SDK format
const aiSdkTools = await tools.toAISDK();

Run the agent loop

Fetch tools
Search & execute

Hand the tools to generateText — the SDK handles multi-step tool calls automatically:

import { openai } from '@ai-sdk/openai';
import { generateText } from 'ai';

const { text } = await generateText({
  model: openai('gpt-5.4'),
  tools: aiSdkTools,
  prompt: 'Get employee details for id: c28xIQaWQ6MzM5MzczMDA2NzMzMzkwNzIwNA',
  maxSteps: 3,
});

Same call — the model first uses tool_search, then tool_execute:

// LLM receives only 2 tools - it searches and executes autonomously
const { text } = await generateText({
  model: openai('gpt-5.4'),
  tools: aiSdkTools,
  prompt: 'List my upcoming Calendly events for the next week.',
  stopWhen: stepCountIs(10),
});

Streaming responses

Build real-time AI applications with streaming:

import { streamText } from 'ai';
import { openai } from '@ai-sdk/openai';

async function streamingAgent(accountId: string, prompt: string) {
  const toolset = new StackOneToolSet();
  const tools = await toolset.fetchTools({ accountIds: [accountId] });
  const aiSdkTools = await tools.toAISDK();

  const result = await streamText({
    model: openai('gpt-5.4'),
    tools: aiSdkTools,
    prompt,
    maxSteps: 5,
  });

  // Stream to client
  for await (const chunk of result.textStream) {
    process.stdout.write(chunk);
  }
}

Multi-tenant support

Handle multiple customer accounts:

async function getAgentForUser(userId: string) {
  // Get user's account IDs from your database
  const accountIds = await db.getUserAccountIds(userId);

  const toolset = new StackOneToolSet();
  const tools = await toolset.fetchTools({ accountIds });

  return await tools.toAISDK();
}

// Usage in API endpoint
app.post('/api/chat', async (req, res) => {
  const { message, userId } = req.body;
  const tools = await getAgentForUser(userId);

  const result = await generateText({
    model: openai('gpt-5.4'),
    tools,
    prompt: message,
  });

  res.json({ response: result.text });
});

Best practices

Account ID from context

// Get from user/tenant context
const accountId = req.user.stackoneAccountId;
const accountId = await getAccountForTenant(tenantId);

Error handling

import { StackOneError } from '@stackone/ai';

try {
  const result = await generateText({ model, tools, prompt });
} catch (error) {
  if (error instanceof StackOneError) {
    console.error('StackOne error:', error.message);
    // Handle gracefully
  }
}

Example

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 raw bytes 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.

Troubleshooting

Execute a tool

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);
}

Calling actions

Streaming responses

Multi-tenant support

Best practices

Account ID from context

Error handling

Example

Troubleshooting

Execute a tool

Next steps

Observability

Tool Defense

​Calling actions

​Streaming responses

​Multi-tenant support

​Best practices

​Account ID from context

​Error handling

​Example

​Troubleshooting

​Execute a tool

​Next steps

Observability

Tool Defense

Calling actions

Streaming responses

Multi-tenant support

Best practices

Account ID from context

Error handling

Example

Troubleshooting

Execute a tool

Next steps