Xagent Docs
Get started

Workforces

A workforce is a team of agents that collaborate on a shared objective. Where a single agent decomposes and executes a task itself, a workforce coordinates several specialised agents — each handling part of the problem — under automatic orchestration.

When to Use a Workforce

  • The goal spans distinct specialisations (e.g. research, drafting, and review)
  • You want agents to hand off intermediate results to one another
  • A single agent's context or toolset is too broad for one configuration

Building a Workforce

Create a workforce, add agent members, and configure how they collaborate. You can build one from scratch, generate it from a prompt, or shape it in the visual builder.

GET  /api/workforces                         # list
POST /api/workforces                         # create
POST /api/workforces/from-prompt             # generate from a description
GET  /api/workforces/agent-options           # selectable agents
POST /api/workforces/{workforce_id}/agents   # add a member
GET  /api/workforces/{workforce_id}/canvas   # visual layout

A prompt sent to from-prompt is capped at 12,000 characters; a longer one is rejected before generation starts.

The Builder

The builder lets you describe changes in natural language; Xagent proposes an updated workforce, which you review and apply:

GET  /api/workforces/{workforce_id}/builder/messages
POST /api/workforces/{workforce_id}/builder/propose
POST /api/workforces/{workforce_id}/builder/apply

Running a Workforce

Start a run and the orchestrator assigns work to member agents, coordinates hand-offs, and aggregates the result:

POST /api/workforces/preview/runs             # try a draft before publishing
POST /api/workforces/{workforce_id}/runs      # run a published workforce
GET  /api/workforces/{workforce_id}/runs      # run history
GET  /api/workforces/{workforce_id}/runs/{run_id}

You can preview a run while the workforce is still a draft, and every run is kept in the workforce's own history so you can revisit what happened.

A run reports Pending, Running, Paused, Completed, Failed, or Cancelled.

Workforce Lifecycle

StatusWhat you can do
DraftKeep building. You can preview runs and discard the draft, but you cannot share it or embed it.
Active (published)Run it, share it, and embed it. Unpublishing returns it to draft.
ArchivedRetired. It cannot be published, shared, or embedded again. Can be unarchived back to draft, or permanently deleted.

Archiving stops work in progress

Archiving a workforce does not only prevent new runs — it cancels runs that are currently active and pauses their tasks. Make sure nothing important is mid-flight before you archive.

Restoring an Archived Workforce

An archived workforce is not necessarily final. Unarchiving restores it to Draft — it does not go straight back to Active, so you publish it again when you are ready to run, share, or embed it.

POST /api/workforces/{workforce_id}/unarchive

Only archived workforces can be unarchived; calling it on a workforce in any other status returns a conflict.

Permanently Deleting a Workforce

The regular delete action archives a workforce, which is reversible. Passing permanent=true instead deletes it outright, in any status — not just archived — and cannot be undone:

DELETE /api/workforces/{workforce_id}?permanent=true

A permanent delete cancels any in-flight runs, then removes the workforce along with its workers, run history, builder conversation, triggers, API keys, and deployment. A manager agent created solely for this workforce is deleted with it; a manager agent shared with something else is kept.

This cannot be undone

Unlike archiving, a permanent delete removes run history and cannot be restored. Archive first if there is any chance you will want the workforce or its history back.

Sharing and Embedding

Like agents, a published workforce can be given a public share link or embedded on your site as a widget. Guests use the same link flow and do not need to know whether a link points to an agent or a workforce.

Two behaviours differ from agents, both deliberately safer:

  • Rotating a link does not switch sharing back on. If sharing was off, rotating the token leaves it off, so resetting a link can never silently re-expose a workforce.
  • The widget starts without a key. A workforce widget key is created only when you enable the widget, not merely by viewing the settings.

Turning sharing or the widget off works even on an archived workforce — you can always revoke access.

Running from Code

Workforces can also be driven programmatically with a runtime key bound to that workforce. See Start a workforce run in the SDK reference.

Runs started from code

A run created through the API is tracked in the workforce's run history, but does not appear in the web app's task list.

Next Steps