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

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.

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.

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