> ## Documentation Index
> Fetch the complete documentation index at: https://docs.stackone.com/llms.txt
> Use this file to discover all available pages before exploring further.
# Vercel AI SDK
> Build AI applications with Vercel AI SDK and StackOne tools
export const GitHubCode = ({url, lang, title, children}) => {
const urlMatch = url?.match(/https:\/\/github\.com\/([^\/]+)\/([^\/]+)\/blob\/([^\/]+)\/(.+?)(?:#L(\d+)(?:-L(\d+))?)?$/);
const owner = urlMatch?.[1];
const repo = urlMatch?.[2];
const branch = urlMatch?.[3];
const filePath = urlMatch?.[4];
const startLine = urlMatch?.[5];
const endLine = urlMatch?.[6];
const getDisplayTitle = () => {
if (title) return title;
if (!filePath) return 'source';
const parts = filePath.split('/');
if (parts.length >= 2) {
return parts.slice(-2).join('/');
}
return parts[parts.length - 1];
};
const displayPath = filePath || 'source';
const displayTitle = getDisplayTitle();
const lineInfo = startLine ? endLine ? `#L${startLine}-L${endLine}` : `#L${startLine}` : '';
const fullUrl = url + (lineInfo && !url.includes('#L') ? lineInfo : '');
const encodedUrl = encodeURIComponent(fullUrl);
const iframeSrc = `https://emgithub.com/iframe.html?target=${encodedUrl}&style=github&type=code&showBorder=on&showLineNumbers=on&showFileMeta=on`;
return ;
};
StackOne tools work with [Vercel AI SDK](https://sdk.vercel.ai/) 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
```bash theme={null}
# 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
```
Two approaches to retrieving tools:
1. [Fetch Tools (with filtering)](/features/tool-discovery#tool-filtering) — fetch all tools upfront with optional filters applied.
2. [Search & Execute](/features/tool-discovery#search-and-execute) — hand the model just `tool_search` + `tool_execute` and let the agent discover what it needs at runtime.
See [Tool Discovery](/features/tool-discovery) for more details on which may be best in your scenario.
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).
```typescript theme={null}
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:
```typescript theme={null}
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();
```
Hand the tools to `generateText` — the SDK handles multi-step tool calls automatically:
```typescript theme={null}
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`:
```typescript theme={null}
// 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:
```typescript theme={null}
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:
```typescript theme={null}
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
```typescript theme={null}
// Get from user/tenant context
const accountId = req.user.stackoneAccountId;
const accountId = await getAccountForTenant(tenantId);
```
### Error handling
```typescript theme={null}
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
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.
```typescript theme={null}
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.
```typescript theme={null}
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);
}
```
## Next steps
Diagnose failing calls and monitor what your agent runs.
Protect your agent from malicious content in tool results.