client

Frameworks → Client → TypeScript | Python (soon)

Superface Client

Note

This is a low-level client, you will need to handle mapping of function definitions & tool calling manually. For framework specific use, please refer to supported frameworks.

Superface SDK lets you integrate external apps with your AI agent using function calling.

This client is optimized for manual handling of tools and is framework agnostic. It allows you to fetch tool definitions, run tools, and manage user connections.

Installation

npm install superface

Usage

Obtain your agent's secret key and connect tools you want your agent to have access to in Superface dashboard.

import Superface from 'superface/client';

const superface = new Superface({
  apiKey: process.env.SUPERFACE_API_KEY,
});

Getting Tool Definitions

const tools = await superface.getTools();

Integrating with LLM

const response = await callLLM({
  tools: tools.map(tool => ({ ... })),
  prompt: '...'
});

Handling Tool Calls

1. Iterate through tool calls as returned from LLM
2. Pass the tool call object from the LLM into runTool() method on Superface Client
3. Add the tool call response to the original chain of messages

// ...
const messages = [{ role: 'user', content: '...' } ];

const response = await callLLm({ ... });

// Handle tool calls
for (const toolCall of toolCalls) {
  const toolRun = await superface.runTool({
    userId: 'example_user',
    name: toolCall.function.name,
    args: JSON.parse(toolCall.function.arguments),
  });

  const toolMessage = {
    role: 'tool',
    content: toolRun.result || toolRun.error
  }
  messages.push(toolMessage);
}

Managing User Connections

const link = await superface.linkToUserConnections({ userId: 'example_user' });
redirect(link.url);

Environment Variables

• SUPERFACE_API_KEY: This value is used to authenticate clients to the Superface API.
• SUPERFACE_CACHE_TIMEOUT: Set in milliseconds to change the cache timeout for tool definitions. The default is 60000ms.
• SUPERFACE_MAX_RETRIES: Maximum number of retries to communicate with Superface servers. This affects getTools and runTool functions.

For more information, refer to the Superface Documentation.