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

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

```typescript theme={null}
import { Workforce } from "@relevanceai/sdk";

const workforce = await Workforce.get("<workforce-id>");
```

To use a specific client instead of the default singleton:

```typescript theme={null}
const workforce = await Workforce.get("<workforce-id>", client);
```

Once loaded, the workforce exposes its metadata:

```typescript theme={null}
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.

```typescript theme={null}
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](/sdk/tasks).

## Continue a conversation

Pass the existing task to `sendMessage` to add follow-up messages:

```typescript theme={null}
await workforce.sendMessage("Include a regional breakdown", task);
```

<Note>
  Unlike agent tasks, workforce tasks don't support file attachments.
</Note>

## Retrieve workforce tasks

### A single task

Fetch a specific task by ID:

```typescript theme={null}
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:

```typescript theme={null}
const tasks = await workforce.getTasks({
  pageSize: 50,
  search: "quarterly report",
});
```

To paginate through results, pass the cursor from the previous response:

```typescript theme={null}
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.

```typescript theme={null}
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.

```typescript theme={null}
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](/sdk/messaging).