Skip to main content
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.