Documentation | HUMΛN Docs

# Multi-Agent Workflow

Orchestrate multiple specialized AI agents to tackle complex, multi-step workflows.

Single agents are powerful, but complex tasks often require multiple specialists. Coordinate them with governed agent calls, HumanOS routing, or builder workflows — not a fantasy client.humanos.createWorkflow() namespace.

When to Use This

✅ Task requires multiple specialized skills (research + writing + review)

✅ You need parallel processing for speed

✅ Steps have dependencies (output of one feeds into another)

✅ You want human checkpoints at critical junctures

Architecture

┌─────────────────────────────────────────────────────┐
│     Your app / builder workflow / humanCall          │
└────────────────────┬────────────────────────────────┘
                     │
         ┌───────────┼───────────┐
         │           │           │
         ▼           ▼           ▼
    ┌────────┐  ┌────────┐  ┌────────┐
    │Agent 1 │  │Agent 2 │  │Agent 3 │
    │Research│  │ Write  │  │ Review │
    └───┬────┘  └───┬────┘  └───┬────┘
        │           │           │
        └───────────┼───────────┘
                    │
                    ▼
         ┌──────────────────────┐
         │   HITL checkpoint    │
         │  /v1/approvals …     │
         └──────────┬───────────┘
                    │
                    ▼
              Final Output

Prerequisites

Delegation JWT (HUMAN_DELEGATION_TOKEN)

Agent IDs or capability URIs you can invoke

Optional: a published builder workflow ID for DAG execution

Implementation

Sequential specialists via `agents.invoke`

SDK:

Governed route (capability-first)

import { HumanClient, humanCall } from '@human/sdk';
const client = new HumanClient({
  delegationToken: process.env.HUMAN_DELEGATION_TOKEN!,
});await humanCall(
  client,
  {
    task_id: crypto.randomUUID(),
    task_type: 'content_pipeline',
    required_capabilities: ['web_research', 'content_planning', 'editorial_review'],
  },
  { delegation: process.env.HUMAN_DELEGATION_TOKEN! },
);

Builder workflows (DAG)

Create / activate workflows via /v1/builder/workflows, then execute on Workforce:

POST /v1/workforce/workflows/{workflowId}/execute
Authorization: Bearer 
Content-Type: application/json{
  "input_data": [{ "topic": "capability-first routing" }]
}

human api POST "/v1/workforce/workflows/$WORKFLOW_ID/execute" \
  --body '{"input_data":[{"topic":"capability-first routing"}]}'

Do not call client.humanos.createWorkflow / ExecuteWorkflow / WaitForWorkflow — those namespaces are not shipped on @human/sdk.

HITL checkpoint

Between steps, resolve approvals as in Human-in-the-Loop:

await client.raw.POST(/v1/approvals/${approvalId}/respond, {
  body: { decision: 'approved', comment: 'Publish' },
});

Security Considerations

DO

Scope each agent call with a least-privilege delegation

Insert HITL approvals before irreversible publish/deploy steps

Prefer humanCall when Fourth Law escalation matters

DON'T

Do not invent client.humanos.createWorkflow fantasy APIs

Chain agent calls without provenance / execution IDs

Skip capability checks between high-risk steps

Multi-agent coordination (alias)

/docs/patterns/humanos/multi-agent-coordination resolves here. Coordination means governed agent calls + workflow steps + HITL checkpoints — not a separate coordination product.