Client

Initialize the SDK client, use the default singleton, or manage multiple clients.

The Client is the authenticated handle the SDK uses to talk to the Relevance AI platform. Most applications only need one.

Initialize with createClient

createClient is the recommended way to set up the SDK. It constructs a Client, registers it as the default singleton, and returns it.

import { createClient, REGION_EU } from "@relevanceai/sdk";

const client = createClient({
  apiKey: "sk-...",
  region: REGION_EU,
  project: "<project-id>",
});

It also accepts a Key instance directly, which is useful when working with embed keys:

import { createClient, Key, REGION_US } from "@relevanceai/sdk";

const key = await Key.generateEmbedKey({
  region: REGION_US,
  project: "<project-id>",
  agentId: "<agent-id>",
});

const client = createClient(key);

For full details on keys, see Authentication.

Call createClient exactly once. It throws if a default client already exists. To work with additional projects or authentication scopes, construct Client instances directly — see Using multiple clients.

The default singleton

Once createClient runs, the client is stored as a global default. Every SDK method that takes an optional client parameter falls back to this default when none is passed.

import { createClient, Client, Agent, REGION_US } from "@relevanceai/sdk";

// Set the default at application startup
createClient({
  apiKey: "sk-...",
  region: REGION_US,
  project: "<project-id>",
});

// Retrieve the default anywhere in the application
const client = Client.default();

// SDK methods pick it up automatically
const agent = await Agent.get("<agent-id>");

This keeps authentication centralized. Initialize the client once during startup, then the rest of the application can interact with agents and workforces without passing the client around.

Using multiple clients

Some apps need to talk to multiple projects, or use different authentication scopes — for example, an API key for admin operations and an embed key for end-user interactions. In those cases, construct Client instances directly and pass them explicitly.

import { Client, Key, Agent, REGION_EU } from "@relevanceai/sdk";

const adminKey = new Key({
  key: "sk-admin-key",
  region: REGION_EU,
  project: "project-one",
});

const userKey = new Key({
  key: "sk-user-key",
  region: REGION_EU,
  project: "project-two",
});

const adminClient = new Client(adminKey);
const userClient = new Client(userKey);

// Pass the client explicitly
const adminAgent = await Agent.get("agent-a", adminClient);
const userAgent = await Agent.get("agent-b", userClient);

Only one client can be the default singleton. When using multiple clients, pass the right instance to every SDK method call.