`ctx.call`

Multi-agent orchestration and human escalation. Call specialized agents, run workflows in parallel, route by capability, or defer to a human when the stakes are too high.

Why it exists

Composition without tight coupling. Call by capability, not by endpoint. Human-in-the-loop: one call to get a human in the loop with proper routing and UI hints—no custom approval UIs or ad-hoc escalation.

How it makes life better

Use ctx.call.agent / ctx.call.route and you get capability-based routing and a clear delegation chain. Use ctx.call.human and you get a full audit trail and built-in approval UX. Bypass with direct HTTP or custom approval flows and you take on routing, audit, and consistency yourself.

The Fourth Law

ctx.call.human() embodies the principle that AI should defer to humans on high-stakes decisions. It's not an escape hatch — it's a first-class workflow step that creates a full audit trail: who was asked, what they decided, how long it took, and why.

`ctx.call.agent(target, input, options?)`

Call another agent. The calling agent's delegation is verified; the target agent runs with a derived delegation that cannot exceed the caller's authority.

typescript

// Call another agent by URI
const result = await ctx.call.agent(
  'agent://org/acme/invoice-processor@v1',
  { invoicePath: '/uploads/invoice-2024.pdf' },
);

console.log(result.data);                   // InvoiceProcessorOutput
console.log(result.execution.cost.usd);     // Cost of the sub-agent call
console.log(result.execution.provenanceId); // Audit trail for the sub-call
console.log(result.delegationChain);        // ['did:agent:abc...', 'did:agent:xyz...']

Addressing modes

typescript

// Three ways to address an agent:

// 1. Agent URI (recommended) — human-readable, org-scoped
await ctx.call.agent('agent://org/acme/invoice-processor@v1', input);
await ctx.call.agent('agent://org/acme/invoice-processor', input); // latest

// 2. Agent DID — cryptographic, immutable reference
await ctx.call.agent('did:agent:7f3a2b9c-4e1d-4a5b-b3c2-8d9e0f1a2b3c', input);

// 3. Capability string — HUMΛN routes to best available agent
await ctx.call.agent('invoice/process', input);

Options

Option	Type	Default	Description
`timeout`	`number`	30000	Max wait time in ms.
`allowSubDelegation`	`boolean`	true	Can the target agent delegate further?
`maxDepth`	`number`	5	Max delegation chain depth.
`retry.maxAttempts`	`number`	3	Retry on transient failures.
`retry.backoff`	`'exponential' \| 'linear' \| 'none'`	'exponential'	Retry backoff strategy.

`ctx.call.human(request)`

Escalate to a human for approval or decision. Execution pauses until the human responds (or timeout expires). The human receives a notification in the HUMΛN dashboard or integrations (Slack, email, etc.) based on their notification preferences.

typescript

// Escalate to a human when the stakes are too high for AI to decide alone
const decision = await ctx.call.human({
  reason: 'Invoice total mismatch — requires human verification before payment',
  context: {
    expected_total: 15000,
    computed_total: 14200,
    vendor: 'Acme Supplies',
    line_items: lineItems,
  },
  requiredCapability: 'finance/approve',
  priority: 'high',
  allowedActions: ['approve', 'reject', 'request-clarification'],
});

if (decision.approved) {
  await processPayment(invoiceId);
  console.log('Approved by:', decision.humanId);
  console.log('Decision time:', decision.metadata.duration, 'ms');
} else {
  console.log('Rejected. Reason:', decision.reason);
}

With a structured UI form

typescript

// Structured approval with a custom UI form
const decision = await ctx.call.human({
  reason: 'New vendor onboarding requires compliance review',
  context: { vendor_name: 'Supplier Co', contract_value: 50000 },
  requiredCapability: 'procurement/approve',
  priority: 'medium',
  ui: {
    type: 'structured',
    fields: [
      { key: 'risk_level', label: 'Risk Level', type: 'select', options: ['low', 'medium', 'high'], required: true },
      { key: 'notes', label: 'Compliance Notes', type: 'textarea', required: false },
    ],
  },
});

console.log('Risk assessed as:', decision.data?.risk_level);

Request fields

Field	Type	Required	Description
`reason`	`string`	Yes	Why escalating. Shown to the human.
`context`	`Record<string, unknown>`	Yes	Data for the human to make an informed decision.
`requiredCapability`	`string`	No	Only humans with this capability can respond.
`timeout`	`number`	No	Max wait in ms. Default: 3600000 (1 hour).
`priority`	`'low' \| 'medium' \| 'high' \| 'critical'`	No	Affects notification urgency.
`allowedActions`	`string[]`	No	e.g. ["approve", "reject", "modify"]
`ui`	`object`	No	Custom UI type and fields for structured decisions.

`ctx.call.parallel(calls)`

Call multiple agents simultaneously. Results arrive together when all complete. Useful for fan-out patterns: gather research, then synthesize.

typescript

// Call multiple agents simultaneously
const [research, competitor, sentiment] = await ctx.call.parallel([
  { agent: 'agent://org/acme/web-researcher', input: { query: topic } },
  { agent: 'agent://org/acme/competitor-analyst', input: { topic } },
  { agent: 'agent://org/acme/sentiment-analyzer', input: { text: context } },
]);

// All three ran concurrently, results available together
const report = await ctx.llm.complete({
  prompt: synthesizePrompt(research.data, competitor.data, sentiment.data),
});

`ctx.call.route(capability, input, options?)`

Route a request to the best available agent with a required capability. HUMΛN matches capability, confidence, cost, and region automatically.

typescript

// Route by capability — HUMΛN finds the best agent
const result = await ctx.call.route(
  'document/extract',    // Required capability
  { documentPath: filePath },
  {
    optimize: 'quality',   // 'quality' or 'cost'
    minConfidence: 0.8,    // Only use agents above this confidence
  }
);

Errors

AccessDeniedErrorCaller does not have permission to call the target agent.

TimeoutErrorAgent call or human escalation exceeded the timeout.

DelegationExpiredErrorThe calling delegation has expired.

NotFoundErrorNo agent found matching the target URI or capability.

In the wild

Reference agents that demonstrate ctx.call in production.

ctx.call.human() chain

multi-level-approval

Manager → VP → CFO escalation with capability-gated approvals at each level.

ctx.call.agent()

newsletter-orchestrator

Multi-agent orchestration: fetch → summarize → send, each step a separate agent call.

ctx.call.human() escalation

invoice-processor

Escalates on total mismatch. Canonical Fourth Law (P10) pattern.

ctx.call

ctx.call.agent(target, input, options?)

Addressing modes

Options

ctx.call.human(request)

With a structured UI form

Request fields

ctx.call.parallel(calls)

ctx.call.route(capability, input, options?)

Errors

In the wild

See Also

`ctx.call`

`ctx.call.agent(target, input, options?)`

`ctx.call.human(request)`

`ctx.call.parallel(calls)`

`ctx.call.route(capability, input, options?)`