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:

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
FIND CANDIDATES
   ├─ POST /v1/capabilities/match (humans + agents)
   └─ Filter by min_confidence, match_strategy, limit
DECIDE & GOVERN
   ├─ POST /v1/humanos/route via humanCall
   ├─ Fourth Law when ai_assessment.confidence is low
   └─ provenance_ref on every decision
EXECUTE OR QUEUE
   ├─ Route to selected executor (pipeline)
   └─ Or create a workforce work-item for human completion

Try it — match then route

REST reference

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

POST /v1/capabilities/match
Content-Type: application/json
Authorization: Bearer 
{
  "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 
X-Trace-ID: 
{
  "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

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

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

Simple Orchestration — beginner-friendly work-item entry point

Human-in-the-Loop — Fourth Law and approval inboxes

Multi-Agent Workflow — coordinate multiple capable agents

Provenance Tracking — audit routing decisions

See Also

humanCall → POST /v1/humanos/route (@human/sdk)

POST /v1/capabilities/match — org-scoped human + agent match

client.workforce.createTask → POST /v1/workforce/work-items

Community: HumanOS autonomic engine

Community: Intent routing architecture