@synaptic-ai/toolcloud

The @synaptic-ai/toolcloud package provides a TypeScript client for interacting with Synaptic's Tool Cloud platform. It seamlessly integrates with OpenAI's API to handle tool calls and authentication flows, allowing you to focus on building your AI agent's functionality rather than managing infrastructure.

Installation

npm install @synaptic-ai/toolcloud

Usage

Basic Setup

import OpenAI from "openai";
import { ToolCloud } from "@synaptic-ai/toolcloud";

// Initialize OpenAI client
const openai = new OpenAI({
  // your OpenAI configuration
});

// Initialize Tool Cloud
const toolCloud = new ToolCloud({
  oauthUrl: "https://your-oauth-url",
  apiKey: "your-api-key"
});

Complete Example with OpenAI Integration

Here's a complete example showing how to use @synaptic-ai/toolcloud with OpenAI's API in a Next.js API route:

import OpenAI from "openai";
import { ToolCloud } from "@synaptic-ai/toolcloud";

const toolCloud = new ToolCloud({
  oauthUrl: "your-oauth-url",
  apiKey: "your-api-key"
});

async function handleToolCalls(messages: any[], tools: any[]) {
  try {
    // Make OpenAI API call with tools
    const chatCompletion = await openai.chat.completions.create({
      messages,
      tools: tools,
      model: "gpt-4", // or your preferred model
    });

    const responseMessage = chatCompletion.choices?.[0].message;

    // If no tool calls, return the response
    if (!responseMessage.tool_calls) {
      return responseMessage;
    }

    // Execute tool calls using Tool Cloud
    const toolExecutionMessage = await toolCloud.execute(
      responseMessage.tool_calls,
      {
        userId: "user-id",
      },
    );

    // Add the assistant's response and tool results to the message history
    const updatedMessages = [
      ...messages,
      responseMessage,
      toolExecutionMessage,
    ];

    // Recursively handle any further tool calls
    return handleToolCalls(updatedMessages, tools);
  } catch (error) {
    console.error("Error in handleToolCalls:", error);
    throw error;
  }
}

// Example API route handler
export async function POST(req: Request) {
  try {
    const { messages } = await req.json();
    
    // Get available tools from Tool Cloud
    const tools = await toolCloud.loadTools();

    const finalMessage = await handleToolCalls(messages, tools);
    return Response.json(finalMessage);
  } catch (error) {
    return Response.json({
      content: "Error",
      status: "error",
    });
  }
}

Getting Available Tools

The loadTools() method retrieves all available tools for your project, including authentication schemas:

// Get available tools from Tool Cloud
const tools = await toolCloud.loadTools();

The returned tools array contains:

• Built-in authentication tools for managing OAuth flows
• All enabled tools for your project based on your API key
• Tool schemas that follow OpenAI's function calling format

Each tool schema includes:

{
  type: "function",
  function: {
    name: string,
    description: string,
    parameters: {
      type: "object",
      properties: {
        // Tool-specific parameters
      },
      required: string[]
    }
  }
}

These tool schemas can be passed directly to OpenAI's API in the tools parameter of chat completion requests.

Authentication

@synaptic-ai/toolcloud handles OAuth authentication flows automatically. When executing a tool that requires authentication:

1. If the user is not authenticated, it will return an auth URL
2. After successful authentication, the tool execution will proceed
3. Authentication state is maintained per user and provider

Execute Response Format

The execute() method returns a Tool Message object that follows OpenAI's message format:

{
  role: "tool",
  content: string, // JSON.stringify(ExecuteResult)
  tool_call_id: string
}

Example responses:

// When authentication is needed
{
  role: "tool",
  content: JSON.stringify({
    output: "https://oauth-provider.com/auth?...",
    skipped: false,
    status: "success",
    function: "your_function_name",
    messageForAI: "User needs to authenticate first. Please direct them to the authentication URL provided in the output."
  }),
  tool_call_id: "call_abc123"
}

// When tool executes successfully
{
  role: "tool",
  content: JSON.stringify({
    output: "tool execution result",
    skipped: false,
    status: "success",
    function: "your_function_name",
    messageForAI: "Tool execution completed successfully."
  }),
  tool_call_id: "call_abc123"
}

// When an error occurs
{
  role: "tool",
  content: JSON.stringify({
    output: "",
    skipped: false,
    status: "error",
    function: "your_function_name",
    messageForAI: "There was an error executing the tool. Please try again or contact support if the issue persists."
  }),
  tool_call_id: "call_abc123"
}

API Reference

ToolCloud

Constructor Options

• baseUrl (string, optional): Base URL for the Tool Cloud API (defaults to http://localhost:8080)
• oauthUrl (string): OAuth service URL
• apiKey (string): Your API key for authentication

Methods

loadTools()

Returns a promise that resolves to an array of available tools, including authentication schemas. These tools can be passed directly to OpenAI's API.

execute(toolCalls, options)

Executes tool calls with authentication handling.

Parameters:

• toolCalls (ChatCompletionMessageToolCall[]): Array of tool calls from OpenAI's response
• options (object):
  • userId (string): ID of the user executing the tools

Returns a promise that resolves to an ExecuteResult containing the tool execution result and status information.