Documentation | HUMΛN Docs

Overview

Route a task to the most qualified resource—whether human, AI agent, or LLM—using capability-first routing. HumanOS automatically finds, verifies, and assigns the best match based on skills, availability, and cost.

Why HumanOS Orchestration?

Capability-First: Routes to resources that can do the work, not just the cheapest

Human + AI: Seamlessly mix humans, agents, and LLMs in workflows

Automatic Fallbacks: If the first choice fails, HumanOS tries the next best option

Provenance: Every routing decision is logged and auditable

Cost-Aware: Among capable resources, HumanOS optimizes for cost

Safety: Built-in guardrails prevent unqualified resources from executing tasks

Think of it like: A smart dispatcher that routes 911 calls to the right responder—not just the closest, but the one with the right skills and equipment.

How Orchestration Works

HumanOS follows a four-step routing process:

1. ANALYZE TASK
   ├─ Extract required capabilities
   ├─ Determine complexity and risk
   └─ Set minimum qualification thresholds
FIND CANDIDATES
   ├─ Query Capability Graph for matches
   ├─ Filter by minimum capability weight
   └─ Check availability and constraints
VERIFY & RANK
   ├─ Cryptographically verify capabilities
   ├─ Rank by capability match quality
   └─ Consider cost among equals
ASSIGN & MONITOR
   ├─ Assign to top-ranked resource
   ├─ Monitor execution with telemetry
   └─ Auto-escalate on errors or low confidence

SDK Examples

SDK:

REST API Example

Create a workforce work-item (HumanOS routes capability-first inside the platform):

POST /v1/workforce/work-items Content-Type: application/json Authorization: Bearer

{ "org_did": "did:org:acme", "title": "Translate user manual from English to Spanish", "description": "Prefer translators with technical_writing evidence", "required_capabilities": ["translation:en-es", "technical_writing"] }

Response (201 Created):

{
  "work_item_id": "wi_a1b2c3d4e5f6",
  "title": "Translate user manual from English to Spanish",
  "status": "open",
  "org_did": "did:org:acme"
}

List open items:

GET /v1/workforce/work-items?org_did=did:org:acme&status=open&limit=10
Authorization: Bearer

Routing Strategies

Routing policy lives server-side in HumanOS / Workforce Cloud. Clients create work items with required_capabilities; they do not call a fantasy HumanOS.routeTask() SDK method.

Strategy	What operators configure	Best for
Capability-first (default)	Minimum evidence weight / capability match	High-stakes, safety-critical work
Cost-informed among capable	Budget ceilings after capability filter	High-volume, budget-bound work
Speed-informed among capable	SLA / start-within windows	Time-sensitive escalations
Balanced	Weighted capability / cost / speed	General-purpose queues

Fallback, escalation, and HITL approval are platform behaviors on the work item — see Human-in-the-Loop and workforce assignment APIs under /v1/orgs/{orgId}/workforce/*.

Monitoring

Track work items with client.workforce.listTasks / getTask, Command Plane Workforce views, and provenance events. Prefer platform telemetry over inventing client-side subscribeToTask helpers.

Human-in-the-Loop Integration

Require human approval for critical work by configuring HITL on the workflow or escalation path — not by a client-side humanApprovalRequired flag on a missing SDK method. See the Human-in-the-Loop pattern.

Enterprise Workflows

Route internal tasks like code reviews, document approvals, and data analysis to qualified employees

Multi-Agent Systems

Orchestrate complex workflows across multiple specialized AI agents

Hybrid Workforces

Seamlessly route between humans, agents, and LLMs based on task requirements

Distributed Teams

Route tasks to the right person regardless of location or timezone

DO

Always verify capabilities before routing critical tasks

Log all routing decisions with provenance for audit trails

Set minimum capability thresholds appropriate for risk level

Implement automatic escalation for low-confidence execution

DON'T

Route high-stakes tasks purely on cost optimization

Skip capability verification to save processing time

Ignore escalation signals from agents or humans

Allow tasks to run indefinitely without timeout safeguards

Next Steps

Learn about Human-in-the-Loop for approval workflows

Explore Multi-Agent Workflows for complex orchestration

Understand Provenance Tracking for audit trails

---

Simple Orchestration