> ## 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.
# OpenAI Integration
> Build AI agents with OpenAI Functions using the StackOne TypeScript AI SDK
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 OpenAI's function calling to build AI agents that access business data.
## Overview
* **Convert tools** to OpenAI function schemas automatically
* **Execute functions** with built-in handling
* **Build agents** with conversational context
* **Multi-step workflows** for complex tasks
```typescript theme={null}
import OpenAI from 'openai';
import { StackOneToolSet } from '@stackone/ai';
/**
* Create agent with tools for a specific account.
*
* In production, accountId comes from:
* - User/tenant context
* - Authentication middleware
* - Database lookup
*/
// Get account ID from your app's auth context or StackOne dashboard
const accountId = 'your-account-id';
const openai = new OpenAI();
const toolset = new StackOneToolSet();
// Fetch tools dynamically for this account
const tools = await toolset.fetchTools({
accountIds: [accountId]
});
// Convert to OpenAI format
const openAITools = tools.toOpenAI();
// Create completion with function calling
const completion = await openai.chat.completions.create({
model: 'gpt-5.4',
messages: [
{
role: 'system',
content: 'You are an HR assistant with access to employee data.'
},
{
role: 'user',
content: 'How many employees do we have?'
}
],
tools: openAITools,
tool_choice: 'auto'
});
// Execute any tool calls
const message = completion.choices[0].message;
if (message.tool_calls) {
for (const toolCall of message.tool_calls) {
const tool = tools.getTool(toolCall.function.name);
if (tool) {
const result = await tool.execute(
JSON.parse(toolCall.function.arguments)
);
console.log('Result:', result.data);
}
}
}
```
## Dynamic Tool Loading
Load tools based on available integrations:
```typescript theme={null}
import { StackOneToolSet } from '@stackone/ai';
const toolset = new StackOneToolSet();
// Load all tools for specific accounts (most common)
const tools = await toolset.fetchTools({
accountIds: ["account-123"]
});
// Optional: Filter by operation type for security
const tools = await toolset.fetchTools({
accountIds: ["account-123"],
actions: ["*_list_*", "*_get_*"] // Only list and get operations (read-only)
});
// Convert to OpenAI format
const openAITools = tools.toOpenAI();
```
## Conversational Agents
Build multi-turn conversational agents:
```typescript theme={null}
import OpenAI from 'openai';
async function runConversationalAgent(accountId: string) {
const openai = new OpenAI();
const toolset = new StackOneToolSet();
const tools = await toolset.fetchTools({ accountIds: [accountId] });
const openAITools = tools.toOpenAI();
const messages: OpenAI.Chat.ChatCompletionMessageParam[] = [
{
role: 'system',
content: 'You are an HR assistant with access to employee data.'
}
];
// Multi-turn conversation loop
while (true) {
const userInput = await getUserInput(); // Your function
if (userInput === 'exit') break;
messages.push({ role: 'user', content: userInput });
const completion = await openai.chat.completions.create({
model: 'gpt-5.4',
messages,
tools: openAITools,
tool_choice: 'auto'
});
const message = completion.choices[0].message;
messages.push(message);
// Execute tool calls if any
if (message.tool_calls) {
for (const toolCall of message.tool_calls) {
const tool = tools.getTool(toolCall.function.name);
if (tool) {
const result = await tool.execute(
JSON.parse(toolCall.function.arguments)
);
messages.push({
role: 'tool',
tool_call_id: toolCall.id,
content: JSON.stringify(result.data)
});
}
}
// Get final response after tool execution
const finalCompletion = await openai.chat.completions.create({
model: 'gpt-5.4',
messages,
});
console.log(finalCompletion.choices[0].message.content);
messages.push(finalCompletion.choices[0].message);
} else {
console.log(message.content);
}
}
}
```
## Best Practices
### Account ID from Context
```typescript theme={null}
// Get from user/tenant context
const accountId = req.user.stackoneAccountId;
const accountId = await getAccountForTenant(tenantId);
```
```typescript theme={null}
// Only expose read operations (optional - for security)
const tools = await toolset.fetchTools({
accountIds: [accountId],
actions: ["*_list_*", "*_get_*"] // Only list and get
});
// Or exclude dangerous operations
const tools = await toolset.fetchTools({
accountIds: [accountId],
actions: ["!*_delete_*"] // Everything except deletes
});
```
## Example
## Agent-Driven Search
Let the LLM discover and execute tools on its own. Instead of loading all tools upfront, pass `tool_search` + `tool_execute` and the LLM finds what it needs:
```typescript theme={null}
const toolset = new StackOneToolSet({
search: { method: 'semantic', topK: 3 },
accountId: 'your-account-id',
});
const tools = toolset.getTools({ accountIds: ['your-account-id'] });
const openaiTools = tools.toOpenAI();
// LLM receives only 2 tools - it searches and executes autonomously
const response = await client.chat.completions.create({
model: 'gpt-5.4',
messages,
tools: openaiTools,
tool_choice: 'auto',
});
```
See [Tool Search](/agents/typescript/tool-search#agent-driven-search) for the full agent loop example.
## Next Steps
* [Basic Usage](/agents/typescript/basic-usage) for fetching and executing tools
* [Tool Search](/agents/typescript/tool-search) for search patterns
* [Tool Filtering](/agents/typescript/tool-filtering) for security
* [Vercel AI SDK](/agents/typescript/frameworks/vercel-ai-sdk) for alternative approach