@relevanceai/sdk 3.0.0-alpha.4 → 3.0.0-alpha.6

package/README.md

@@ -1,15 +1,15 @@
 # Relevance AI JavaScript SDK
 
 A comprehensive JavaScript/TypeScript SDK for building AI-powered applications
-with Relevance AI's workforce platform. Build, deploy, and scale AI agents
+with Relevance AI's workforce platform. Build, deploy, and scale AI workforces
 across any JavaScript runtime.
 
 ## Description
 
 The Relevance AI JavaScript SDK provides a unified interface for integrating
-AI agents into your applications. Whether you're building server-side
-applications, browser-based interfaces, or edge computing solutions, this SDK
-delivers consistent, type-safe access to Relevance AI's powerful agent
+AI workforces and agents into your applications. Whether you're building
+server-side applications, browser-based interfaces, or edge computing solutions,
+this SDK delivers consistent, type-safe access to Relevance AI's powerful agent
 ecosystem.
 
 ### Key Features
@@ -18,13 +18,11 @@ ecosystem.
   Cloudflare Workers, and browsers
 - **Event-Driven Architecture**: Real-time updates via native EventTarget API
 - **Type Safety**: Full TypeScript support with comprehensive type definitions
-- **Multi-Client Support**: Manage multiple projects and authentication scopes
-  simultaneously
 - **Zero Dependencies**: Built on web standards for minimal footprint
 
 ## Quick Start
 
-Get up and running with AI agents in under 5 minutes:
+Get up and running in seconds:
 
 ```typescript
 import { Agent, createClient, EU_REGION } from "@relevanceai/sdk";
@@ -36,16 +34,25 @@ const client = createClient({
   project: process.env.PROJECT_ID,
 });
 
-// Load an agent and start a conversation
+// Load an agent
 const agent = await Agent.get("agent-id");
+// Start a conversation
 const task = await agent.sendMessage("Hello, how can you help me today?");
-
 // Listen for agent responses
 task.addEventListener("message", ({ detail: { message } }) => {
   if (message.isAgent()) {
     console.log("Agent:", message.text);
   }
 });
+
+// Or use a workforce of agents
+
+import { Workforce } from "@relevanceai/sdk";
+
+// Load the workforce
+const workforce = await Workforce.get("workforce-id");
+// Start delegating
+const task = await workforce.sendMessage("Analyze this complex dataset");
 ```
 
 ## Installation
@@ -123,7 +130,7 @@ Configure your bundler to use the shim:
 
 The SDK supports two authentication methods for different use cases:
 
-#### API Keys (Server-side)
+#### API Keys (server-side)
 
 API keys grant full access to your project. Use these for server applications
 and secure environments:
@@ -152,10 +159,12 @@ const key = new Key({
 const client = new Client(key);
 ```
 
-#### Embed Keys (Client-side)
+#### Embed Keys (client-side)
 
 For public-facing applications, use embed keys which are scoped to a specific
-public agent:
+public agent. Embed keys need to be generated and should be stored in your
+applications local storage or database. Each embed key corresponds to a single
+agent or workforce.
 
 ```typescript
 import { Key, createClient, US_REGION } from "@relevanceai/sdk";
@@ -169,105 +178,159 @@ const embedKey = await Key.generateEmbedKey({
 const client = createClient(embedKey);
 ```
 
-### Fetching Agents
+### Agents
 
-Load agents before creating tasks:
+#### Loading agents
 
 ```typescript
-// Using default client
+// fetch all agents (with pagination)
+const agents = await Agent.getAll({ pageSize: 20, page: 1 });
+
+// fetch all agents with custom page size
+const agents = await Agent.getAll({ pageSize: 50, page: 3 });
+
+// fetch all agents using default options (pageSize: 20, page: 1)
+const agents = await Agent.getAll();
+
+// using the default client
 const agent = await Agent.get("agent-id");
 
-// Using specific client
-const customClient = createClient({
-  /* config */
-});
-const agent = await Agent.get("agent-id", customClient);
+// or using a specific client
+const agent = await Agent.get("agent-id", client);
 
-// Access agent properties
+// accessing agent properties
 console.log(agent.name);
 console.log(agent.avatar);
 console.log(agent.description);
 ```
 
-### Sending Messages
-
-#### Create a New Task
+#### Sending messages
 
-Start a new conversation with an agent:
+Use `Agent#sendMessage()` to send messages to an agent.
 
 ```typescript
-const agent = await Agent.get("agent-id");
+// create a new task
 const task = await agent.sendMessage("What's the weather like today?");
+
+// reply to existing tasks
+await agent.sendMessage("What about tomorrow?", task);
+
+// sending attachments
+const contents = await Deno.readFile("./contract.pdf");
+const contract = new File([contents], "contract.pdf", {
+  type: "application/pdf",
+});
+await agent.sendMessage("Summarize this contract", [contract]);
+```
+
+Note: `Agent#sendMessage()` returns once the message is sent and doesn't wait for
+a response. See Tasks for handling message events.
+
+#### Retrieving tasks
+
+Fetch and filter tasks for an agent:
+
+```typescript
+// specific task
+const task = await agent.getTask("<task-id>");
+
+// pagination
+const tasks = await agent.getTasks({
+  pageSize: 10,
+  page: 1,
+  sort: { updatedAt: "desc" },
+});
+
+// filtering
+const activeTasks = await agent.getTasks({
+  filter: { status: ["queued", "running", "idle"] },
+});
+
+// searching
+const searchResults = await agent.getTasks({
+  search: "weather",
+  sort: { createdAt: "asc" },
+});
+```
+
+### Workforces
+
+#### Loading workforces
+
+```typescript
+// using the default client
+const workforce = await Workforce.get("<workforce-id>");
+
+// or with a specific client
+const workforce = await Workforce.get("<workforce-id>", client);
+
+// accessing workforce properties
+console.log(workforce.name);
 ```
 
-#### Send to Existing Task
+#### Sending messages
 
-Continue an existing conversation:
+Use `Workforce#sendMessage()` to send messages to a workforce.
 
 ```typescript
-// Get an existing task
-const task = await agent.getTask("task-id");
+// create a new task
+const task = await agent.sendMessage("What's the weather like today?");
 
-// Send a follow-up message
+// reply to existing tasks
 await agent.sendMessage("What about tomorrow?", task);
 ```
 
-Note: `sendMessage` returns once the message is sent and doesn't wait for a
-response. Use event listeners to handle responses.
+Note: `Workforce#sendMessage()` returns once the message is sent and doesn't
+wait for a response. See Tasks for handling message events.
+
+#### Retrieving tasks
+
+Load existing workforce tasks.
+
+```typescript
+const task = await workforce.getTask("<task-id>");
+```
 
-### Event Handling
+### Tasks
 
-Tasks use an event-driven architecture for real-time updates:
+Agents and workforces, subjects, all return an instance of a `Task` when sending
+messages. Tasks dispatch events as they would occur on the the subjects timeline
+in the Relevance AI workforce platform.
 
 #### Available Events
 
-- **`start`**: Task initialization
-- **`status`**: Status changes (queued, running, complete, error)
-- **`message`**: New messages from agent or user
-- **`update`**: Tool execution updates
+- **`update`**: Whenever a subject has been update.
+- **`message`**: Unified event for all message types
 - **`error`**: Error notifications
 
 #### Listening for Events
 
 ```typescript
-// Listen for messages
-task.addEventListener("message", ({ detail }) => {
-  const { message } = detail;
-
+// Listen for all messages (agent, user, and tool)
+task.addEventListener("message", ({ detail: { message } }) => {
+  // use message helpers to determine the message
   if (message.isAgent()) {
     console.log("Agent:", message.text);
+  } else if (message.isUser()) {
+    console.log("User:", message.text);
+  } else if (message.isTool()) {
+    console.log("Tool:", message.status);
   }
 });
 
-// Listen for status changes
-task.addEventListener("status", ({ detail }) => {
-  console.log("Status changed to:", detail.status);
-});
-
-// Listen for tool updates
-task.addEventListener("update", ({ detail }) => {
-  console.log("Tool update:", detail.message);
+// catching errors
+task.addEventListener("error", ({ detail: { message } }) => {
+  console.error("Task error:", message.lastError);
 });
-
-// Listen for errors
-task.addEventListener("error", ({ detail }) => {
-  console.error("Task error:", detail.message);
-});
-
-// Clean up when done
-task.unsubscribe();
 ```
 
-#### Managing Subscriptions
+#### Unsubscribing
 
-The SDK automatically starts listening when you add event listeners. Remember
-to clean up:
+It's important that you unsubscribe from tasks once they have moved out of
+scope in your application. This will prevent memory leaks by removing dead
+subscriptions.
 
 ```typescript
-// Start listening (called automatically with addEventListener)
-task.subscribe();
-
-// Stop listening and clean up
 task.unsubscribe();
 ```
 
@@ -283,6 +346,7 @@ createClient({ apiKey, region, project });
 
 // Access anywhere in your app
 import { Client } from "@relevanceai/sdk";
+
 const client = Client.default();
 ```
 
@@ -319,10 +383,12 @@ For complete working examples, check out the `internal/examples` directory:
 
 - **Deno Examples** (`internal/examples/deno/`):
 
-  - Client setup and configuration
-  - Creating and managing tasks
-  - Fetching agent information
-  - Retrieving existing tasks
+  - (Agent) Creating tasks
+  - (Agent) Getting a task
+  - (Agent) Getting all agents
+  - (Agent) Getting all tasks
+  - (Agent) Getting an agent
+  - (Workforce) Creating a task
 
 - **Browser Example** (`internal/examples/browser/`):
   - Full chat application with Preact
@@ -336,6 +402,7 @@ For complete working examples, check out the `internal/examples` directory:
 ```typescript
 class Client {
   constructor(key: Key);
+
   static default(): Client;
 
   readonly key: Key;
@@ -343,7 +410,9 @@ class Client {
   readonly project: string;
 
   isEmbedKey(): boolean;
+
   fetch<T>(endpoint: string, init?: RequestInit): Promise<T>;
+
   url(path: string): URL;
 }
 
@@ -370,7 +439,9 @@ class Key {
   readonly taskPrefix?: string;
 
   isEmbed(): boolean;
+
   fetchHeaders(): HeadersInit;
+
   toJSON(): CreateKeyOptions;
 }
 
@@ -395,6 +466,11 @@ interface GenerateEmbedKeyOptions {
 class Agent {
   static async get(id: string, client?: Client): Promise<Agent>;
 
+  static async getAll(
+    options?: GetAllOptions,
+    client?: Client
+  ): Promise<Agent[]>;
+
   readonly id: string;
   readonly name?: string;
   readonly description?: string;
@@ -405,31 +481,83 @@ class Agent {
   readonly project: string;
 
   getTask(taskId: string): Promise<Task>;
-  sendMessage(message: string, task?: Task): Promise<Task>;
+
+  getTasks(): Promise<Task[]>;
+  getTasks(options: GetTaskOptions): Promise<Task[]>;
+
+  sendMessage(message: string): Promise<Task>;
+  sendMessage(message: string, task: Task): Promise<Task>;
+  sendMessage(
+    message: string,
+    attachments: (File | Attachment)[]
+  ): Promise<Task>;
+  sendMessage(
+    message: string,
+    attachments: (File | Attachment)[],
+    task: Task
+  ): Promise<Task>;
+}
+
+interface Attachment {
+  fileName: string;
+  fileUrl: string;
+}
+
+interface GetTaskOptions {
+  pageSize?: number; // default: 100
+  page?: number; // default: 1
+  // default: { createdAt: "asc" }
+  sort?: { createdAt: "asc" | "desc" } | { updatedAt: "asc" | "desc" };
+  search?: string;
+  filter?: {
+    status?: TaskStatus[];
+  };
+}
+
+interface GetAllOptions {
+  pageSize?: number; // default: 20
+  page?: number; // default: 1
 }
 ```
 
-### Task
+### Workforce
 
 ```typescript
-class Task extends EventTarget {
-  static async get(
-    id: string,
-    agentOrAgentId: Agent | string,
-    client?: Client
-  ): Promise<Task>;
+class Workforce {
+  static async get(id: string, client?: Client): Promise<Workforce>;
 
+  readonly id: string;
+  readonly name: string;
+  readonly region: Region;
+  readonly project: string;
+
+  getTask(taskId: string): Promise<Task>;
+
+  sendMessage(message: string): Promise<Task>;
+  sendMessage(message: string, task: Task): Promise<Task>;
+}
+```
+
+### Task
+
+```typescript
+class Task<T extends Agent | Workforce = Agent> extends EventTarget {
   readonly id: string;
   readonly title: string;
   readonly status: TaskStatus;
-  readonly agent: Agent;
+  readonly subject: Agent | Workforce;
 
   isRunning(): boolean;
-  getMessages(options?: { from?: Date }): Promise<AnyTaskMessage[]>;
+
+  getMessages(): Promise<AnyTaskMessage[]>;
+  getMessages(options: { from: Date }): Promise<AnyTaskMessage[]>;
+
   subscribe(): void;
+
   unsubscribe(): void;
 
   addEventListener(type: string, listener: EventListener): void;
+
   removeEventListener(type: string, listener: EventListener): void;
 }
 
@@ -439,46 +567,60 @@ type TaskStatus =
   | "queued"
   | "running"
   | "action"
-  | "complete"
+  | "completed"
   | "error";
 ```
 
 ### Messages
 
 ```typescript
-abstract class TaskMessage {
+abstract class GenericMessage {
   readonly id: string;
   readonly type: MessageType;
   readonly createdAt: Date;
 
-  isAgent(): boolean;
+  isAgent(): boolean; // Check if message is from agent
+  isUser(): boolean; // Check if message is from user
+  isTool(): boolean; // Check if message is a tool execution
+  isAgentError(): boolean; // Check if message is an agent error
 }
 
-class AgentMessage extends TaskMessage {
+class AgentMessage extends GenericMessage {
   readonly text: string;
 }
 
-class UserMessage extends TaskMessage {
+class UserMessage extends GenericMessage {
   readonly text: string;
 }
 
-class ToolMessage extends TaskMessage {
-  readonly status: "pending" | "running" | "completed" | "failed";
-}
+class ToolMessage extends GenericMessage {
+  readonly status: "cancelled" | "pending" | "running" | "completed" | "failed";
+  readonly tool?: Tool; // Available when message is from a tool (not subagent)
+  readonly toolOrAgentId: string; // ID of the tool or subagent
 
-class AgentErrorMessage extends TaskMessage {
-  readonly error: string;
+  isSubAgent(): boolean; // Check if this is a subagent execution
+  subAgentTaskId: string | null; // Task ID if this is a subagent, null otherwise
 }
+
+class AgentErrorMessage extends GenericMessage {}
+
+class WorkforceAgentMessage extends GenericMessage {}
+
+class WorkforceAgentHandoverMessage extends GenericMessage {}
 ```
 
-### Types
+### Tool
 
 ```typescript
-type Region = "us" | "eu" | "au";
-
-const US_REGION: Region = "us";
-const EU_REGION: Region = "eu";
-const AU_REGION: Region = "au";
+class Tool {
+  readonly id: string;
+  readonly name: string;
+  readonly avatar?: string;
+  readonly description?: string;
+  readonly region: Region;
+  readonly project: string;
+  readonly parametersSchema: JSONSchema4;
+}
 ```
 
 ## Contributing
@@ -514,9 +656,10 @@ deno run dnt
 ### Current
 
 - [x] Core client functionality
-- [x] Agent and task creation
+- [x] Task creation
 - [x] Event-driven messaging
 - [x] Multi-environment support
+- [x] Workforce support
 
 ### Upcoming Features
 
@@ -524,7 +667,6 @@ deno run dnt
 - [ ] File upload support
 - [ ] Enhanced error recovery
 - [ ] Agent and task management
-- [ ] Workforce support
 - [ ] Tool support
 
 ### Future Considerations (2.0)

package/esm/agent.d.ts

@@ -1,29 +1,68 @@
-import { Client } from "./client.js";
+import { type Attachment, Client } from "./client.js";
 import type { Region } from "./region.js";
-import { Task } from "./task.js";
-interface AgentConfig {
+import { Task, type TaskStatus } from "./task/task.js";
+export interface AgentConfig {
     agent_id: string;
     public: boolean;
+    project: string;
     name?: string;
     description?: string;
     emoji?: string;
     insert_date_: string;
     update_date_: string;
+    model: string;
 }
+export type AgentTaskState = "idle" | "starting-up" | "running" | "pending-approval" | "waiting-for-capacity" | "cancelled" | "timed-out" | "escalated" | "unrecoverable" | "paused" | "completed" | "errored-pending-approval" | "queued-for-approval" | "queued-for-rerun";
+/**
+ * Converts an AgentTaskState to a simplified TaskStatus.
+ *
+ * @dev
+ *   We want to simplify because our states are simplified in the UI and also
+ *   some states have combined reasoning that the consumer does not need to care
+ *   about. i.e. "queued-for-approval" "queued-for-rerun" should just be "queued".
+ *
+ * @param {AgentTaskState} state The agent task state to convert.
+ * @returns {TaskStatus} The simplified task status.
+ */
+export declare function stateToStatus(state: AgentTaskState): TaskStatus;
+type SortDirection = "asc" | "desc";
+type GetTaskOptionSort = {
+    createdAt: SortDirection;
+} | {
+    updatedAt: SortDirection;
+};
+type GetTaskOptions = {
+    pageSize?: number;
+    page?: number;
+    sort?: GetTaskOptionSort;
+    search?: string;
+    filter?: {
+        status?: TaskStatus[];
+    };
+};
+type GetAllOptions = {
+    pageSize?: number;
+    page?: number;
+};
 export declare class Agent {
     #private;
-    private readonly client;
     static get(id: string, client?: Client): Promise<Agent>;
+    static getAll({ page, pageSize, }?: GetAllOptions, client?: Client): Promise<Agent[]>;
+    private readonly client;
     constructor(config: AgentConfig, client: Client);
     get id(): string;
+    get region(): Region;
+    get project(): string;
     get name(): string | undefined;
     get description(): string | undefined;
     get avatar(): string | undefined;
     get createdAt(): Date;
     get updatedAt(): Date;
-    get region(): Region;
-    get project(): string;
-    getTask(taskId: string): Promise<Task>;
-    sendMessage(message: string, task?: Task): Promise<Task>;
+    getTask(taskId: string): Promise<Task<Agent>>;
+    getTasks({ sort, pageSize, page, search, filter, }?: GetTaskOptions): Promise<Task<Agent>[]>;
+    sendMessage(message: string): Promise<Task<Agent>>;
+    sendMessage(message: string, task: Task<Agent>): Promise<Task<Agent>>;
+    sendMessage(message: string, attachments: (Attachment | File)[]): Promise<Task<Agent>>;
+    sendMessage(message: string, attachments: (Attachment | File)[], task: Task<Agent>): Promise<Task<Agent>>;
 }
 export {};