Skip to main content
HUMΛN

Simple Orchestration

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

2. FIND CANDIDATES
   ├─ Query Capability Graph for matches
   ├─ Filter by minimum capability weight
   └─ Check availability and constraints

3. VERIFY & RANK
   ├─ Cryptographically verify capabilities
   ├─ Rank by capability match quality
   └─ Consider cost among equals

4. 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 <DELEGATION_TOKEN>

{
  "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 <DELEGATION_TOKEN>

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

See Also

← All patterns