Skip to content
Aerostack v1.0-beta

OpenAI SDK Integration

Use Aerostack workspace tools as OpenAI function-calling tools. Full control over the tool call loop — inspect, modify, or batch tool calls as needed.

Install

Section titled “Install”
Terminal window
npm install @aerostack/sdk-openai openai

Quick Start

Section titled “Quick Start”
import OpenAI from 'openai';
import { getTools, handleToolCalls } from '@aerostack/sdk-openai';


const openai = new OpenAI();
const config = { workspace: 'my-workspace', token: 'mwt_...' };


const { tools } = await getTools(config);


const response = await openai.chat.completions.create({
  model: 'gpt-4o',
  messages: [{ role: 'user', content: 'Create a GitHub issue for the login bug' }],
  tools,
});


const toolCalls = response.choices[0]?.message.tool_calls;
if (toolCalls) {
  const results = await handleToolCalls(toolCalls, config);
  // results are ChatCompletionToolMessageParam[] — append to messages and continue
}

The SDK:

  1. Fetches all MCP tools from your workspace
  2. Converts them to ChatCompletionTool[] format (sanitizing names to fit OpenAI’s 64-char limit)
  3. handleToolCalls executes tool calls in parallel against the workspace gateway
  4. Results come back as ChatCompletionToolMessageParam[] — append to messages for the next turn

Multi-Turn Conversation

Section titled “Multi-Turn Conversation”

Build a full agentic loop:

import OpenAI from 'openai';
import { getTools, handleToolCalls } from '@aerostack/sdk-openai';


const openai = new OpenAI();
const config = { workspace: 'my-workspace', token: 'mwt_...' };
const { tools } = await getTools(config);


const messages: OpenAI.ChatCompletionMessageParam[] = [
  { role: 'user', content: 'Check Stripe for failed payments this week, then post a summary to Slack' },
];


// Agentic loop — run until the model stops calling tools
while (true) {
  const response = await openai.chat.completions.create({
    model: 'gpt-4o',
    messages,
    tools,
  });


  const choice = response.choices[0];
  messages.push(choice.message);


  if (!choice.message.tool_calls?.length) {
    // Model is done — print final response
    console.log(choice.message.content);
    break;
  }


  // Execute tool calls and append results
  const results = await handleToolCalls(choice.message.tool_calls, config);
  messages.push(...results);
}

Single Tool Call

Section titled “Single Tool Call”

For finer control, handle one tool call at a time:

import { handleToolCall } from '@aerostack/sdk-openai';


// Execute a single tool call
const result = await handleToolCall(
  response.choices[0].message.tool_calls[0],
  config,
);
Section titled “Factory Pattern (Recommended for Production)”
import { createAerostackOpenAI } from '@aerostack/sdk-openai';


const aerostack = createAerostackOpenAI({
  workspace: 'my-workspace',
  token: process.env.AEROSTACK_WORKSPACE_TOKEN!,
});


// Reuse across requests — caches the name map after first tools() call
const { tools } = await aerostack.tools();
const results = await aerostack.handleToolCalls(toolCalls);

What getTools Returns

Section titled “What getTools Returns”
const result = await getTools(config);


result.tools    // ChatCompletionTool[] — pass to chat.completions.create({ tools })
result.nameMap  // Map<string, string> — sanitized name → original MCP tool name
result.raw      // McpTool[] — raw MCP tool definitions for inspection

The nameMap is used internally by handleToolCalls to resolve sanitized tool names back to their original MCP names. You only need it if you’re handling tool execution manually.

Next Steps

Section titled “Next Steps”