Skip to main content

Documentation Index

Fetch the complete documentation index at: https://relevanceai.com/docs/llms.txt

Use this file to discover all available pages before exploring further.

A workforce is a team of agents that coordinate to handle complex, multistep tasks through delegation and handover. The platform routes messages to the right agent, and agents can pass work between each other as the task progresses — your application doesn’t have to manage the coordination.

​
Load a workforce

Fetch a workforce by ID. The workforce ID is available on the workforce’s page in the dashboard. 
import { Workforce } from "@relevanceai/sdk";

const workforce = await Workforce.get("<workforce-id>");
To use a specific client instead of the default singleton: 
const workforce = await Workforce.get("<workforce-id>", client);
Once loaded, the workforce exposes its metadata: 
console.log(workforce.name);    // display name
console.log(workforce.id);      // unique identifier
console.log(workforce.region);  // deployment region
console.log(workforce.project); // project identifier

​
Start a workforce task

Send a message with sendMessage. This creates a new task and returns it immediately. The workforce begins routing the message to the appropriate agent. 
const task = await workforce.sendMessage(
  "Analyze last quarter's sales data and prepare a summary"
);
As with agent tasks, sendMessage resolves when the message is sent, not when the workforce finishes. Listen for events on the returned task to receive results — see Tasks.

​
Continue a conversation

Pass the existing task to sendMessage to add follow-up messages: 
await workforce.sendMessage("Include a regional breakdown", task);
Unlike agent tasks, workforce tasks don’t support file attachments.

​
Retrieve workforce tasks

​
A single task

Fetch a specific task by ID: 
const task = await workforce.getTask("<task-id>");

​
A list of tasks

Fetch a list of workforce tasks with getTasks. Workforce task listing uses cursor-based pagination and supports search: 
const tasks = await workforce.getTasks({
  pageSize: 50,
  search: "quarterly report",
});
To paginate through results, pass the cursor from the previous response: 
const firstPage = await workforce.getTasks({ pageSize: 20 });

// Use the cursor from the response to get the next page
const nextPage = await workforce.getTasks({
  pageSize: 20,
  cursor: "<cursor-from-previous-page>",
});

​
Differences from agent task retrieval

Workforce and agent task listings don’t support the same options:
FeatureAgent tasksWorkforce tasks
PaginationPage-basedCursor-based
Sort optionsSupportedNot supported
Status filteringSupportedNot supported
SearchSupportedSupported
File attachmentsSupportedNot supported

​
Workforce task states

Workforce tasks use a different set of internal states than agent tasks. The SDK maps them to the same simplified statuses used elsewhere.
Workforce stateSDK status
runningrunning
completedcompleted
execution-limit-reachederror
pending-approvalaction
escalatedaction
errored-pending-approvalerror
The action status means the workforce needs human intervention — either through an approval step or because the task was escalated.

​
Workforce-specific messages

Workforce tasks emit two message types that don’t appear in agent tasks.

​
Agent run messages

A WorkforceAgentMessage (type "workforce-agent-run") indicates that an agent within the workforce is executing a subtask. These messages include details about which agent is running and the current state of its work. 
task.addEventListener("message", ({ detail }) => {
  const { message } = detail;

  if (message.type === "workforce-agent-run") {
    // An agent in the workforce is working
  }
});

​
Handover messages

A WorkforceAgentHandoverMessage (type "workforce-agent-handover") indicates that work is being delegated from one agent to another. The message includes the trigger message that started the handover and details about the receiving agent. 
task.addEventListener("message", ({ detail }) => {
  const { message } = detail;

  if (message.type === "workforce-agent-handover") {
    // Work is being handed to another agent
  }
});
These messages appear interleaved with standard agent and tool messages in the event stream. For full details on all message types and type guards, see Messaging.