Workforces

Trigger multi-agent workforces, continue conversations, and handle handover messages.

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:

Feature	Agent tasks	Workforce tasks
Pagination	Page-based	Cursor-based
Sort options	Supported	Not supported
Status filtering	Supported	Not supported
Search	Supported	Supported
File attachments	Supported	Not 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 state	SDK status
running	running
completed	completed
execution-limit-reached	error
pending-approval	action
escalated	action
errored-pending-approval	error

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.