> ## 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
> Build AI agents with OpenAI function calling using the StackOne Agent SDK for TypeScript or Python
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.
**Supported languages:** TypeScript and Python.
* **Convert tools** to OpenAI function schemas automatically
* **Execute functions** with built-in handling
* **Build conversational agents** with tool execution
* **Multi-step workflows** for complex tasks
## Calling actions
```bash TypeScript theme={null}
# Requires Node.js 16.0 or higher
# TypeScript 4.5 or higher (recommended)
# Using npm
npm install @stackone/ai openai
# Using pnpm
pnpm add @stackone/ai openai
# Using yarn
yarn add @stackone/ai openai
# Using bun
bun add @stackone/ai openai
export STACKONE_API_KEY=your_api_key_here
```
```bash Python theme={null}
# Requires Python 3.10 or higher
# Using uv (recommended)
uv add 'stackone-ai[mcp]' openai
# Using pip
pip install 'stackone-ai[mcp]' openai
# Optional: install with example dependencies
uv add 'stackone-ai[mcp,examples]'
pip install 'stackone-ai[mcp,examples]'
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, following the `provider_operation_entity` tool naming (e.g. `workday_*`, or `*_list_*` for read-only tools).
```typescript TypeScript theme={null}
import OpenAI from 'openai';
import { StackOneToolSet } from '@stackone/ai';
// 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.
// 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 OpenAI function format
const openAITools = tools.toOpenAI();
```
```python Python theme={null}
from openai import OpenAI
from stackone_ai import StackOneToolSet
# Initialise clients
client = OpenAI()
toolset = StackOneToolSet()
# Fetch StackOne tools.
# Optionally narrow the fetch with filters:
# providers=["hibob", "workday"] — only these connectors
# actions=["*_list_*", "*_get_*"] — glob patterns, e.g. read-only actions
tools = toolset.fetch_tools(
actions=['workday_get_worker', 'workday_list_workers'],
account_ids=['your-account-id']
)
# Convert to OpenAI function format
openai_tools = tools.to_openai()
```
The LLM receives only 2 tools and searches the catalog autonomously:
```typescript 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 OpenAI function format — the agent loop also uses
// `tools` to execute the calls the model makes
const openAITools = tools.toOpenAI();
```
```python Python theme={null}
from stackone_ai import StackOneToolSet
toolset = StackOneToolSet(
search={"method": "semantic", "top_k": 3},
execute={"account_ids": ["your-account-id"]},
)
# LLM receives only 2 tools - it searches and executes autonomously.
# .openai() returns OpenAI-format tools directly, so no conversion is needed
openai_tools = toolset.openai(mode="search_and_execute")
```
Create the completion with the tools attached, then execute any tool calls the model makes:
```typescript TypeScript theme={null}
// 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);
}
}
}
```
```python Python theme={null}
# Create an AI agent with tool access
response = client.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 are in engineering?"
}
],
tools=openai_tools,
tool_choice="auto"
)
# Handle tool calls
message = response.choices[0].message
if message.tool_calls:
for tool_call in message.tool_calls:
tool = tools.get_tool(tool_call.function.name)
if tool:
result = tool.execute(tool_call.function.arguments)
print(f"Result: {result}")
```
The model first calls `tool_search`, then `tool_execute` — the same loop as the Fetch tools tab, run until the model stops calling tools:
```typescript TypeScript theme={null}
// Route every tool call through the toolset and feed the result
// back until the model stops
import OpenAI from 'openai';
const client = new OpenAI();
const messages: OpenAI.ChatCompletionMessageParam[] = [
{
role: 'system',
content:
'Use tool_search to find relevant tools, then tool_execute to run them. ' +
'Read parameter schemas from tool_search results carefully.',
},
{ role: 'user', content: 'List my upcoming Calendly events for the next week.' },
];
for (let step = 0; step < 10; step++) {
const response = await client.chat.completions.create({
model: 'gpt-5.4',
messages,
tools: openAITools,
tool_choice: 'auto',
});
const choice = response.choices[0];
if (!choice.message.tool_calls?.length) {
console.log(choice.message.content);
break;
}
messages.push(choice.message);
for (const toolCall of choice.message.tool_calls) {
// Look the meta tool up in the collection from the fetch step
const tool = tools.getTool(toolCall.function.name);
const result = tool
? await tool.execute(toolCall.function.arguments)
: { error: `Tool "${toolCall.function.name}" not found` };
messages.push({
role: 'tool',
tool_call_id: toolCall.id,
content: JSON.stringify(result),
});
}
}
```
```python Python theme={null}
# Route every tool call through the toolset and feed the result
# back until the model stops
import json
from openai import OpenAI
client = OpenAI()
messages = [
{
"role": "system",
"content": (
"Use tool_search to find relevant tools, then tool_execute to run them. "
"Read parameter schemas from tool_search results carefully."
),
},
{"role": "user", "content": "List my upcoming Calendly events for the next week."},
]
for _step in range(10):
response = client.chat.completions.create(
model="gpt-5.4",
messages=messages,
tools=openai_tools,
tool_choice="auto",
)
choice = response.choices[0]
if not choice.message.tool_calls:
print(choice.message.content)
break
messages.append(choice.message.model_dump(exclude_none=True))
for tool_call in choice.message.tool_calls:
result = toolset.execute(tool_call.function.name, tool_call.function.arguments)
messages.append({
"role": "tool",
"tool_call_id": tool_call.id,
"content": json.dumps(result),
})
```
## Example
A full runnable example:
```python theme={null}
from stackone_ai.models import StackOneError, StackOneAPIError
try:
result = employee_tool.call(id="employee-123")
print("Success:", result)
except StackOneAPIError as e:
print(f"API error: {e.message}")
except StackOneError as e:
print(f"StackOne error: {e.message}")
except Exception as e:
print(f"Unexpected error: {e}")
```
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.
**TypeScript** — 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`. |
**Python** — `call()` and `execute()` both return the dict directly (it isn't wrapped in a result object), so read its values with dict keys like `result["content"]`.
```python theme={null}
tools = toolset.fetch_tools(actions=["googledrive_*"], account_ids=["your-account-id"])
download = tools.get_tool("googledrive_unified_download_file")
result = download.execute({"id": "file-id"})
# result describes the file. Write the bytes straight to disk:
with open(result["file_name"] or "download.bin", "wb") as f:
f.write(result["content"])
```
The returned dict, from both `call()` and `execute()`:
| Key | Type | Description |
| -------------- | ------------- | ------------------------------------------------------------------------------ |
| `content` | `bytes` | Raw file bytes. Not JSON-serializable (see note). |
| `content_type` | `str` | File MIME type (for example `application/pdf`), or `application/octet-stream`. |
| `status_code` | `int` | HTTP status of the download response. |
| `headers` | `dict` | Response headers. |
| `file_name` | `str \| None` | Filename from `Content-Disposition` (RFC 5987 `filename*` aware), else `None`. |
`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 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);
}
```
```python Python theme={null}
tools = toolset.fetch_tools(account_ids=["your-account-id"])
employee_tool = tools.get_tool("workday_list_workers")
# call() with keyword arguments
result = employee_tool.call(id="employee-123", include_details=True)
print(result["data"])
# execute() with dictionary payloads
result = employee_tool.execute({"id": "employee-123", "include_details": True})
# execute() with OpenAI-style arguments
payload = {"arguments": {"id": "employee-123"}}
result = employee_tool.execute(payload)
```
## Next steps
Diagnose failing calls and monitor what your agent runs.
Protect your agent from malicious content in tool results.