Skip to main content
Get from zero to a live agent conversation in five steps. This quickstart uses Node.js — for other runtimes, see Installation.
1

Install the SDK

npm install @relevanceai/sdk
Yarn, pnpm, Bun, and Deno are all supported. See Installation for the full matrix.
2

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.
3

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.
4

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.
5

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.

Authentication

Use embed keys for browser apps, or API keys for server code.

Tasks

Understand task status, events, and cleanup.

Messaging

Handle tool calls, user messages, attachments, and errors.

Streaming

Render responses as the agent types them.