Quickstart

Install the SDK

npm install @relevanceai/sdk

Yarn, pnpm, Bun, and Deno are all supported. See Installation for the full matrix.

Grab your credentials

From the Relevance AI dashboard, go to Integrations & API Keys and generate a Relevance API key. You’ll also need your project ID and the region your project is deployed in.

For a walkthrough, see API integration.

Create a client

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

createClient({
  apiKey: process.env.RELEVANCE_API_KEY,
  region: REGION_US,
  project: process.env.RELEVANCE_PROJECT_ID,
});

createClient stores the client as the default singleton, so you don’t need to pass it around. Replace REGION_US with REGION_EU or REGION_AU to match your project.

Load an agent and send a message

import { Agent } from "@relevanceai/sdk";

const agent = await Agent.get("<agent-id>");
const task = await agent.sendMessage("What can you help me with?");

sendMessage returns a Task immediately — it doesn’t wait for the agent to respond. The agent ID is visible on the agent’s page in the dashboard.

Listen for the response

task.addEventListener("message", ({ detail: { message } }) => {
  if (message.isAgent()) {
    console.log("Agent:", message.text);
  }
});

Messages arrive through the "message" event on the task. Use the type guards (isAgent, isTool, isTyping, and so on) to handle each kind. When the conversation is done, call task.unsubscribe() to release the connection.