RFC-AON-0001
Adaptive Observability Negotiation (AON)
Status: Draft Standard
Version: 1.0.0
Date: 3 Oct 2026
Category: Standards Track
Author: FullAgenticStack Initiative
Dependencies: RFC-WF-0001, RFC-WF-0002
License: Open Specification (Public, Royalty-Free)
Abstract
The Adaptive Observability Negotiation (AON) standard defines an architectural mechanism for RESTful APIs that allows clients to dynamically negotiate the level of response observability.
AON bridges the gap between traditional "Black Box" models (returning only final results) and "Glass Box" models (streaming execution telemetry, heuristic decisions, and self-healing attempts) in real-time using the same transaction connection. It also introduces the "Human-in-the-Healing-Loop" (HIHL) pattern through Interactive Intent-Healing (IIH).
Keywords
Adaptive Observability, NDJSON, SSE, WebSocket, Intent-Healing, Human-in-the-Healing-Loop, Glass Box API, Telemetry Streaming.
1. Scope
This specification defines the communication protocol and data structures for adaptive observability. It covers:
- Dynamic content negotiation for execution telemetry.
- Multi-channel event distribution (NDJSON, SSE, WebSocket).
- Structured schemas for intent analysis and self-healing events.
- Interactive intervention protocols for manual error recovery.
2. Normative Language
The key words "MUST", "MUST NOT", "SHOULD", and "MAY" are to be interpreted as described in standards practice.
3. Core Principles
AON is built on three pillars of the Full Agent Stack:
- Adaptive Visibility: The system MUST reveal its "reasoning" and internal state changes to specialized clients without breaking legacy compatibility.
- Resilience Awareness: Clients MUST be notified of autonomous healing actions taken by the backend (e.g., token refreshes, schema corrections).
- Interactive Recovery: When autonomous healing fails, the system SHOULD request human intervention before emitting a terminal error.
4. Protocol Handshake (Handshake Negotiation)
AON leverages HTTP Content Negotiation (RFC 7231) to determine the observability level.
4.1. Standard Mode (Black Box)
For legacy clients or simple browsers.
-
Header:
Accept: application/json(or omitted). - Behavior: The server MUST execute all logic and return ONLY the final payload once processing is complete.
4.2. Agent Mode (Glass Box)
For AI dashboards, advanced CLIs, and conversational interfaces.
-
Header:
Accept: application/x-ndjson. - Behavior: The server MUST respond immediately with streaming headers and transmit events line-by-line (NDJSON).
-
MIME Type:
application/x-ndjson. -
Transfer Encoding:
chunked.
5. Live Telemetry Channels
The system SHOULD provide three synchronized output channels for observability events.
5.1. NDJSON (Direct Response)
Used for backend-to-backend streaming.
- Individual JSON objects separated by
\n. - The first line SHOULD contain channel metadata (Session ID, WebSocket/SSE URLs).
5.2. SSE (Browser Telemetry)
Ideal for one-way dashboard telemetry.
- Event mirroring follows the NDJSON stream logic.
- Format:
event: <type>\ndata: <json>\nid: <id>\n\n.
5.3. WebSocket (Interactive Interactivity)
Required for bidirectionality and Interactive Intent-Healing.
- Mirrored logs plus the capability to receive healing patches.
6. Interactive Intent-Healing (HIHL)
When autonomous self-healing strategies fail, the system transitions to Interactive Intent-Healing (IIH).
6.1. The Healing Request (AON-REQ-1)
The system MUST emit a interactive_healing_request event containing:
- Specific error description.
- Whitelist of allowed patch paths.
- Contextual snapshot for decision making.
6.2. The Patch Application (AON-REQ-2)
Human intervention MUST be submitted as a JSON Patch (RFC 6902).
- If the patch is valid, the system MUST apply it to the operational payload and retry the failed step.
- If denied or timed out, the system MUST emit a terminal error.
7. Event Schemas (NDJSON Structure)
All AON events MUST contain a type and timestamp.
7.1. intent_analysis
Emitted when the agent interprets input and alters the execution path.
{
"type": "intent_analysis",
"timestamp": 1715432000,
"original_intent": "create_user",
"decision": "apply_semantic_mapping"
}
7.2. healing (Self-Healing)
Emitted during active autonomous healing actions.
{
"type": "healing",
"severity": "medium",
"action": "refresh_token",
"metadata": { "attempt": 1 }
}
7.3. interactive_healing_request (Intervention)
Emitted to request human input.
{
"type": "interactive_healing_request",
"error": { "code": "schema_mismatch" },
"allowedPatchPaths": ["/userId"]
}
8. Implementation Guidelines
8.1. Hub Architecture
Implementations SHOULD use a central AON Event Hub to ensure a single source of truth for NDJSON, SSE, and WebSocket distribution.
8.2. Replay Buffer
Systems SHOULD maintain a short-lived ring buffer per session to allow clients connecting to SSE/WS mid-request to replay missed telemetry.
9. Security Considerations
- Redaction: Healing events MUST NEVER leak original/expired credentials or internal connection strings.
- Environment Gating: Detailed intent analysis SHOULD be restricted in production environments using JWT Role-based access.
- Path Whitelisting: Interactive patches MUST be restricted to a predefined list of "safe" paths to prevent arbitrary code/data execution.
10. Compliance Verification
An implementation is considered AON-Compliant if it:
- [ ] Strictly respects the
Acceptheader for mode switching. - [ ] Provides valid NDJSON output without breaking legacy fallbacks.
- [ ] Incorporates a trace correlation ID (
trace_id) across all events. - [ ] Implements at least one autonomous healing strategy (AP-01).
11. Conclusion
Adaptive Observability Negotiation transforms static APIs into living, resilient agents. By moving from a "Black Box" to an "Interactive Glass Box," AON provides the necessary visibility for AI-native development and high-availability systems.
Top comments (0)