Skip to main content
HUMΛN

Capability routing

Overview

Select the executor that can do the work — human, agent, or model — before you optimize for cost or speed. Capability routing is HUMΛN's Principle Twelve in practice: filter to qualified resources, rank by match quality, then consider cost among equals.

Two shipped surfaces implement the pattern:

Surface Path Role
Capability Graph match POST /v1/capabilities/match Find humans and agents in an org who cover required_capabilities
HumanOS route POST /v1/humanos/route Governed routing decision with Fourth Law escalation and provenance
Workforce work-items POST /v1/workforce/work-items Durable queue entries routed capability-first inside the platform

There is no fantasy HumanOS.routeTask() namespace. Use humanCall, raw REST, or client.workforce.createTask.

Why capability-first routing?

  • Revelation, not exclusion: Capabilities describe demonstrated fit — not opaque scores or leaderboards
  • Safety: Unqualified executors never receive high-stakes work
  • Cost-informed: Among capable resources, HumanOS prefers minimum viable cost
  • Provenance: Every routing decision is logged with reasoning
  • Fourth Law: Low confidence escalates to humans — see Human-in-the-Loop

Think of it like: A hospital triage nurse — you need the right specialist, not whoever answered the phone first.

How routing works

HumanOS follows a four-step process (policy lives server-side; clients declare requirements):

1. DECLARE REQUIREMENTS
   ├─ required_capabilities on the task or route body
   ├─ org context (org_id / org_did)
   └─ optional task_description for semantic / hybrid match

2. FIND CANDIDATES
   ├─ POST /v1/capabilities/match (humans + agents)
   └─ Filter by min_confidence, match_strategy, limit

3. DECIDE & GOVERN
   ├─ POST /v1/humanos/route via humanCall
   ├─ Fourth Law when ai_assessment.confidence is low
   └─ provenance_ref on every decision

4. EXECUTE OR QUEUE
   ├─ Route to selected executor (pipeline)
   └─ Or create a workforce work-item for human completion

Try it — match then route

>
SDK:

REST reference

Match capabilities — returns humans, agents, capability_gap, and matched_count:

POST /v1/capabilities/match
Content-Type: application/json
Authorization: Bearer <DELEGATION_TOKEN>

{
  "org_id": "acme",
  "required_capabilities": ["translation:en-es", "technical_writing"],
  "include_humans": true,
  "include_agents": true,
  "min_confidence": 0.5,
  "match_strategy": "exact",
  "limit": 20
}

Route task — returns routing_decision, routing_id, provenance_ref; Fourth Law when confidence is low:

POST /v1/humanos/route
Content-Type: application/json
Authorization: Bearer <DELEGATION_TOKEN>
X-Trace-ID: <optional-uuid>

{
  "task_id": "t_01jabc",
  "task_type": "invoice_approval",
  "required_capabilities": ["accounting"],
  "ai_assessment": { "confidence": 0.95 },
  "escalation_recommendation": false
}

When fourth_law_triggered is true, resolve via Human-in-the-Loop — do not silently retry.

Workforce work-items (work-item routing)

For tasks that land in a human inbox, create a work item and let HumanOS route capability-first inside Workforce Cloud:

const orgDid = process.env.HUMAN_ORG_DID!;

const task = await client.workforce.createTask({
  org_did: orgDid,
  title: 'Approve invoice INV-2026-001',
  description: 'Finance review before payment release',
  required_capabilities: ['accounting', 'invoice_processing'],
});

const open = await client.workforce.listTasks({
  org_did: orgDid,
  status: 'open',
  limit: 10,
});

// Optional explicit assign when you already picked a match
if (open.data[0]?.work_item_id) {
  await client.workforce.assign(
    open.data[0].work_item_id,
    orgDid,
    'did:human:finance-lead',
  );
}

Assignment, completion, and cancellation use POST /v1/workforce/work-items/{id}/action with action_id of assign, complete, or cancel.

Routing strategies

Strategy Request field Best for
Exact match_strategy: "exact" Hard capability IDs, compliance-bound work
Semantic match_strategy: "semantic" + task_description Natural-language task specs
Hybrid match_strategy: "hybrid" Default balance of ID + description

Server-side HumanOS policy chooses cost/speed weighting after the capability filter. Clients declare required_capabilities; they do not implement ranking math.

Enterprise queues

Route code reviews, approvals, and analysis to qualified employees — not whoever is online

Agent mesh

Match org agents whose scopes cover required capabilities before invoking them

Hybrid workforce

Combine /capabilities/match discovery with humanCall execution and workforce fallbacks

Escalation paths

When capability_gap is true, surface HITL instead of assigning unqualified executors

DO

Call POST /v1/capabilities/match before high-stakes humanCall when you need visibility into capability_gap

Pass required_capabilities on every route and work-item create

Handle EscalationRequiredError and route to /v1/approvals

Log routing_id and provenance_ref for audit

DON'T

Route purely on cost without required_capabilities

Invent HumanOS.routeTask / routeTaskByCapability SDK methods

Ignore capability_gap=true and assign anyway

Hide Fourth Law escalation from operators

Capability Graph routing (alias)

Community posts may link /docs/patterns/capability-graph/routing or /docs/patterns/capability-graph/route-task-by-capability. Those URLs are aliases of this pattern.

The Graph match endpoint is POST /v1/capabilities/match — same request body as the Try it section above. Pair it with humanCall when you need a governed routing decision, not just a candidate list.

Prefer this page (capability-routing) in new links.

Workforce route-task (alias)

/docs/patterns/workforce/route-task and /docs/patterns/humanos/workforce-routing deep-link here. Workforce routing is client.workforce.createTask plus platform assignment — see the workforce chapter above.

Related alias: capability-first task routing.

Next Steps

See Also

← All patterns