Agent Routing Spec

Version: 1.0.0. Last updated: 2026-02-28.

1. Scope

This spec defines how a single agent is selected for a capability request: intent capture, candidate ranking, deterministic selection, and outcome recording.

2. Requirements

• Routing decisions MUST be deterministic for the same (trace_id, intent_key, requested_capability).
• Implementations MUST record outcomes (success/failure, latency, optional receipt) when execution is performed.
• Ranking SHOULD use historical success rate and latency; when trusted execution receipts exist, ranking SHOULD prefer trusted stats.
• Selection MAY use exploration (e.g. random among top-K) with a deterministic seed derived from the routing decision id.
• Decision id MUST be a stable string (e.g. route:trace_id:intent_key:capability) for idempotency and citation.

3. Example payloads

3.1 Route decision (internal)

Input: traceId, businessId, requested_capability, intent_key
Output: decision_id, intent_id, selected_agent_id, selected_endpoint_url

3.2 Outcome record

traceId, intentId, intentKey, agentId, success, latencyMs, nctCost, optional: receipt_hash, receipt_verified

4. Changelog

• 1.0.0 (2026-02-28): Initial release; deterministic decision id, outcome recording, optional verifiable receipts.

5. Compatibility

Callers that do not send receipt data still receive routing and outcomes; trusted_trials increment only when receipt_verified is true.