Individual Submission S. E. Efstathiou Internet-Draft Independent Intended status: Experimental 17 August 2026 Expires: 18 February 2027 Simple Agent Management Protocol (SAMP) draft-efstathiou-samp-agent-management-00 Abstract The Simple Agent Management Protocol (SAMP) defines a lightweight management-plane protocol for heterogeneous AI agents. SAMP allows a management system to discover agents, query their state, receive events, subscribe to event streams, and optionally configure or execute explicitly exposed operations under policy control. SAMP is inspired by operational management protocols such as SNMP, but it is designed for AI-agent-specific concepts such as dynamic profiles, autonomy classes, enrollment, trust states, and policy- gated execution. It is not an agent-to-agent communication protocol, an agent tool-use protocol, or an agent framework specification. This document defines SAMP version 0.1 as an Experimental protocol suitable for controlled environments and independent interoperability testing. Status of This Memo This Internet-Draft is submitted in full conformance with the provisions of BCP 78 and BCP 79. Internet-Drafts are working documents of the Internet Engineering Task Force (IETF). Note that other groups may also distribute working documents as Internet-Drafts. The list of current Internet- Drafts is at https://datatracker.ietf.org/drafts/current/. Internet-Drafts are draft documents valid for a maximum of six months and may be updated, replaced, or obsoleted by other documents at any time. It is inappropriate to use Internet-Drafts as reference material or to cite them other than as "work in progress." This Internet-Draft will expire on 18 February 2027. Copyright Notice Copyright (c) 2026 IETF Trust and the persons identified as the document authors. All rights reserved. Efstathiou Expires 18 February 2027 [Page 1] Internet-Draft SAMP August 2026 This document is subject to BCP 78 and the IETF Trust's Legal Provisions Relating to IETF Documents (https://trustee.ietf.org/ license-info) in effect on the date of publication of this document. Please review these documents carefully, as they describe your rights and restrictions with respect to this document. Code Components extracted from this document must include Revised BSD License text as described in Section 4.e of the Trust Legal Provisions and are provided without warranty as described in the Revised BSD License. Table of Contents 1. Introduction . . . . . . . . . . . . . . . . . . . . . . . . 4 1.1. Scope . . . . . . . . . . . . . . . . . . . . . . . . . . 5 1.2. Relationship to Existing Protocols . . . . . . . . . . . 6 2. Terminology . . . . . . . . . . . . . . . . . . . . . . . . . 7 3. Architecture . . . . . . . . . . . . . . . . . . . . . . . . 8 3.1. Roles . . . . . . . . . . . . . . . . . . . . . . . . . . 8 4. Agent Lifecycle and Trust States . . . . . . . . . . . . . . 9 4.1. Trust Transitions . . . . . . . . . . . . . . . . . . . . 9 4.2. Enrollment . . . . . . . . . . . . . . . . . . . . . . . 10 4.3. Agent Bootstrap and Manager Location . . . . . . . . . . 11 5. SAMP Profile . . . . . . . . . . . . . . . . . . . . . . . . 11 5.1. Required Identity Fields . . . . . . . . . . . . . . . . 12 5.2. Category and Field Model . . . . . . . . . . . . . . . . 12 5.3. Minimal Required Category . . . . . . . . . . . . . . . . 13 5.4. Profile Validation . . . . . . . . . . . . . . . . . . . 13 5.5. Profile Format . . . . . . . . . . . . . . . . . . . . . 14 6. Autonomy Classes . . . . . . . . . . . . . . . . . . . . . . 14 7. Protocol Operations . . . . . . . . . . . . . . . . . . . . . 14 7.1. PDU Directions . . . . . . . . . . . . . . . . . . . . . 15 7.2. PDU Exchange Patterns . . . . . . . . . . . . . . . . . . 16 7.3. Authentication Requirements by PDU . . . . . . . . . . . 16 7.4. DISCOVER Rate Limiting . . . . . . . . . . . . . . . . . 16 7.5. SUBSCRIBE and UNSUBSCRIBE Semantics . . . . . . . . . . . 16 8. Message Format . . . . . . . . . . . . . . . . . . . . . . . 17 8.1. Common PDU Envelope . . . . . . . . . . . . . . . . . . . 17 8.1.1. Field Validation Rules . . . . . . . . . . . . . . . 18 8.1.2. Request/Response Correlation . . . . . . . . . . . . 19 8.1.3. Timestamp Validation . . . . . . . . . . . . . . . . 19 8.1.4. Sequence Numbers . . . . . . . . . . . . . . . . . . 19 8.2. PDU-Specific Payloads . . . . . . . . . . . . . . . . . . 19 8.2.1. PING . . . . . . . . . . . . . . . . . . . . . . . . 19 8.2.2. DISCOVER . . . . . . . . . . . . . . . . . . . . . . 20 8.2.3. QUERY . . . . . . . . . . . . . . . . . . . . . . . . 20 8.2.4. PUSH . . . . . . . . . . . . . . . . . . . . . . . . 21 8.2.5. SUBSCRIBE . . . . . . . . . . . . . . . . . . . . . . 21 8.2.6. UNSUBSCRIBE . . . . . . . . . . . . . . . . . . . . . 22 8.2.7. CONFIG . . . . . . . . . . . . . . . . . . . . . . . 22 Efstathiou Expires 18 February 2027 [Page 2] Internet-Draft SAMP August 2026 8.2.8. EXEC . . . . . . . . . . . . . . . . . . . . . . . . 23 8.3. Error Envelope . . . . . . . . . . . . . . . . . . . . . 24 8.4. Error Codes . . . . . . . . . . . . . . . . . . . . . . . 24 8.5. JSON Encoding Requirements . . . . . . . . . . . . . . . 26 8.6. Behavior for Unknown Fields and Unknown PDU Types . . . . 26 9. Authentication . . . . . . . . . . . . . . . . . . . . . . . 26 9.1. Authentication Model . . . . . . . . . . . . . . . . . . 26 9.2. HMAC-SHA256 Signing . . . . . . . . . . . . . . . . . . . 27 9.3. Key Identification . . . . . . . . . . . . . . . . . . . 27 9.4. Canonical JSON . . . . . . . . . . . . . . . . . . . . . 28 9.4.1. Canonicalization Procedure . . . . . . . . . . . . . 28 9.4.2. Signature Representation . . . . . . . . . . . . . . 28 9.4.3. Verification Procedure . . . . . . . . . . . . . . . 28 9.4.4. Failure Behavior . . . . . . . . . . . . . . . . . . 28 9.4.5. Unicode Normalization . . . . . . . . . . . . . . . . 29 10. Transport Mapping . . . . . . . . . . . . . . . . . . . . . . 29 10.1. HTTP Transport . . . . . . . . . . . . . . . . . . . . . 29 10.1.1. HTTP Method . . . . . . . . . . . . . . . . . . . . 29 10.1.2. Content-Type . . . . . . . . . . . . . . . . . . . . 29 10.1.3. Endpoint Path . . . . . . . . . . . . . . . . . . . 30 10.1.4. HTTP Status Codes . . . . . . . . . . . . . . . . . 30 10.1.5. HTTPS Requirements . . . . . . . . . . . . . . . . . 30 10.2. WebSocket Transport . . . . . . . . . . . . . . . . . . 31 10.3. Retry and Backoff . . . . . . . . . . . . . . . . . . . 31 11. Conformance . . . . . . . . . . . . . . . . . . . . . . . . . 32 11.1. Mandatory Implementation Requirements . . . . . . . . . 32 11.2. Conformance Testing . . . . . . . . . . . . . . . . . . 32 12. Security Considerations . . . . . . . . . . . . . . . . . . . 33 12.1. Threat Model . . . . . . . . . . . . . . . . . . . . . . 33 12.1.1. Rogue Managers . . . . . . . . . . . . . . . . . . . 33 12.1.2. Rogue Agents . . . . . . . . . . . . . . . . . . . . 33 12.1.3. Credential Theft . . . . . . . . . . . . . . . . . . 34 12.1.4. Replay Attacks . . . . . . . . . . . . . . . . . . . 34 12.1.5. Profile Spoofing . . . . . . . . . . . . . . . . . . 34 12.1.6. Unauthorized CONFIG and EXEC . . . . . . . . . . . . 35 12.1.7. Version Downgrade . . . . . . . . . . . . . . . . . 35 12.1.8. Event and Discovery Flooding . . . . . . . . . . . . 35 12.1.9. Registry Poisoning . . . . . . . . . . . . . . . . . 36 12.2. Audit Requirements . . . . . . . . . . . . . . . . . . . 36 12.3. Rate Limiting and Back-Pressure . . . . . . . . . . . . 36 12.4. Trust Bootstrap . . . . . . . . . . . . . . . . . . . . 36 12.5. Token Rotation and Storage . . . . . . . . . . . . . . . 36 12.6. Summary: Current Requirements vs Future Work . . . . . . 37 13. Privacy Considerations . . . . . . . . . . . . . . . . . . . 37 13.1. Sensitive Metadata Exposure . . . . . . . . . . . . . . 37 13.2. Event Data Sensitivity . . . . . . . . . . . . . . . . . 38 13.3. Data Minimization . . . . . . . . . . . . . . . . . . . 38 13.4. Log Protection . . . . . . . . . . . . . . . . . . . . . 38 Efstathiou Expires 18 February 2027 [Page 3] Internet-Draft SAMP August 2026 14. Operational Considerations . . . . . . . . . . . . . . . . . 38 14.1. Network Placement . . . . . . . . . . . . . . . . . . . 38 14.2. Scaling . . . . . . . . . . . . . . . . . . . . . . . . 38 14.3. Observability . . . . . . . . . . . . . . . . . . . . . 39 14.4. Error Handling in Practice . . . . . . . . . . . . . . . 39 15. IANA Considerations . . . . . . . . . . . . . . . . . . . . . 39 15.1. SAMP PDU Types Registry . . . . . . . . . . . . . . . . 40 15.2. SAMP Error Codes Registry . . . . . . . . . . . . . . . 40 15.3. SAMP Autonomy Classes Registry . . . . . . . . . . . . . 42 15.4. SAMP Trust States Registry . . . . . . . . . . . . . . . 42 15.5. SAMP Profile Namespaces Registry . . . . . . . . . . . . 43 15.6. Media Type Registration . . . . . . . . . . . . . . . . 43 16. Implementation Status . . . . . . . . . . . . . . . . . . . . 43 17. References . . . . . . . . . . . . . . . . . . . . . . . . . 44 17.1. Normative References . . . . . . . . . . . . . . . . . . 44 17.2. Informative References . . . . . . . . . . . . . . . . . 45 Appendix A. Open Issues . . . . . . . . . . . . . . . . . . . . 46 Appendix B. Example SAMP Profile (TOML) . . . . . . . . . . . . 47 Appendix C. Example PDU Flows . . . . . . . . . . . . . . . . . 47 C.1. Discovery Flow . . . . . . . . . . . . . . . . . . . . . 47 C.2. Query Flow . . . . . . . . . . . . . . . . . . . . . . . 47 C.3. Event Subscription Flow . . . . . . . . . . . . . . . . . 48 Appendix D. Glossary . . . . . . . . . . . . . . . . . . . . . . 48 Author's Address . . . . . . . . . . . . . . . . . . . . . . . . 49 1. Introduction AI agents are increasingly deployed as long-running services, assistants, automation workers, coding agents, operational copilots, and autonomous or semi-autonomous control loops. These agents are commonly built with different frameworks, runtime environments, model providers, memory systems, and tool interfaces. Operators need a consistent way to observe and manage these agents without depending on framework-specific APIs. SAMP defines a management-plane interface between a SAMP Manager and a SAMP Agent. The protocol covers discovery, enrollment, heartbeat, state query, asynchronous event notification, subscription, configuration, and controlled execution. SAMP deliberately does not define how agents reason, how models are selected, how tools are invoked, or how agents communicate with each other. Those concerns belong to other layers. Efstathiou Expires 18 February 2027 [Page 4] Internet-Draft SAMP August 2026 This document specifies SAMP version 0.1, intended for controlled environments such as private data centers, research labs, and operator networks where a management system needs visibility into and control of AI agents. SAMP v0.1 is not intended for untrusted networks without additional security mechanisms. 1.1. Scope SAMP v0.1 defines: * A JSON-based message format and common PDU envelope. * Nine PDU types covering discovery, heartbeat, query, event notification, subscription, configuration, and execution. * A profile model for agent identity, exposed fields, and policy declarations. * Trust states and an enrollment model. * Autonomy classes as advisory metadata for manager policy. * HMAC-SHA256 message authentication. * HTTP(S) as the baseline transport. * Conformance tiers. * IANA registry framework. SAMP v0.1 does NOT define: * Federation or multi-manager coordination. * Fleet-wide bulk or transactional operations. * Role-based access control (RBAC). * Mandatory mutual TLS (mTLS). * A formal profile schema language (e.g., JSON Schema, YANG). * Agent-to-agent communication. * Agent tool-use interfaces. * Model selection or inference protocols. Efstathiou Expires 18 February 2027 [Page 5] Internet-Draft SAMP August 2026 1.2. Relationship to Existing Protocols SAMP occupies the AI agent management plane. It is intended to coexist with existing management, telemetry, tool, and agent- communication protocols. SNMP SAMP is SNMP-inspired, but not SNMP-compatible. SNMP [RFC3411]/[RFC3416] is device-centric and based on MIB objects [RFC2578]/[RFC2579]/[RFC2580] and GET/SET/TRAP operations. SAMP adds AI-agent concepts such as dynamic profiles, autonomy classes, enrollment, trust states, and policy-gated execution. NETCONF/YANG NETCONF [RFC6241] and YANG [RFC7950] provide strong configuration and modeling facilities for network devices. SAMP targets agent lifecycle, discovery, trust, and runtime management. A future SAMP profile model could be mapped to YANG, but that is outside this document. OpenTelemetry OpenTelemetry provides observability for traces, metrics, and logs. SAMP can export or correlate events with observability systems, but it defines management operations that observability systems do not provide. OpenTelemetry OpAMP The Open Agent Management Protocol (OpAMP) [OPAMP] manages telemetry and data-collection agents. SAMP addresses autonomous and semi-autonomous AI agents as operational entities. The two protocols are complementary and can coexist in the same management architecture. A deployment may use OpAMP for its telemetry collectors and SAMP for its AI agents, with a unified management dashboard. MCP MCP [MCP] is a tool-use interface for applications and agents. SAMP is a management interface for operators and management systems. A2A and ACP Agent-to-agent protocols [A2A] define peer communication and collaboration. SAMP defines manager-to-agent management. Efstathiou Expires 18 February 2027 [Page 6] Internet-Draft SAMP August 2026 +=====================+===============+==========================+ | Layer | Protocol | Purpose | +=====================+===============+==========================+ | Tool use | MCP | Agent-to-tool invocation | +---------------------+---------------+--------------------------+ | Agent communication | A2A / ACP | Agent-to-agent | | | | collaboration | +---------------------+---------------+--------------------------+ | Observability | OpenTelemetry | Traces, metrics, logs | +---------------------+---------------+--------------------------+ | Telemetry agent | OpAMP | Manage data-collection | | management | | agents | +---------------------+---------------+--------------------------+ | AI agent management | SAMP | Manage autonomous/semi- | | | | autonomous AI agents | +---------------------+---------------+--------------------------+ Table 1: Protocol Layer Comparison 2. Terminology The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", "SHOULD", "SHOULD NOT", "RECOMMENDED", "NOT RECOMMENDED", "MAY", and "OPTIONAL" in this document are to be interpreted as described in BCP 14 [RFC2119] [RFC8174] when, and only when, they appear in all capitals, as shown here. The following terms are defined for use in this document: SAMP Agent An AI agent that exposes a SAMP management interface. SAMP Manager A system that manages one or more SAMP Agents using SAMP. SAMP Profile A structured document that declares the identity, exposed categories, fields, capabilities, and policy-relevant properties of a SAMP Agent. PDU Protocol Data Unit. A SAMP message envelope and its payload. Autonomy Class A profile attribute that describes the operational risk class of an agent. It is used as an input to manager policy, but does not by itself grant authority. Enrollment The process by which a manager evaluates an announced agent and assigns an initial trust state. Trust State The manager's state for an agent, such as discovered, Efstathiou Expires 18 February 2027 [Page 7] Internet-Draft SAMP August 2026 pending, trusted, quarantined, rejected, offline, stale, or revoked. Conformance Tier A defined level of protocol support that an implementation may claim. See Section 11. 3. Architecture The basic SAMP architecture contains a manager and one or more agents: +--------------+ SAMP +--------------+ | SAMP Manager | <-----------------> | SAMP Agent | | | | | | Registry | | Profile | | Policy | | State | | Scheduler | | Capabilities | +--------------+ +--------------+ A SAMP Agent maintains a SAMP Profile and exposes SAMP operations. A SAMP Manager maintains a registry, evaluates trust, applies policy, and initiates management operations. SAMP is a management protocol. It does not require a specific agent framework, model provider, orchestration system, memory backend, or tool protocol. 3.1. Roles SAMP Manager: * Maintains a registry of known agents. * Evaluates agent trust and applies policy. * Initiates QUERY, CONFIG, EXEC, SUBSCRIBE, and UNSUBSCRIBE operations. * Receives PING, DISCOVER, and PUSH from agents. * Returns DISCOVER_ACK in response to DISCOVER. SAMP Agent: * Maintains a SAMP Profile describing its identity and capabilities. * Sends DISCOVER to announce itself to a manager. Efstathiou Expires 18 February 2027 [Page 8] Internet-Draft SAMP August 2026 * Sends periodic PING heartbeats. * Responds to QUERY requests. * Emits PUSH events. * Accepts or rejects CONFIG and EXEC based on profile and local policy. * Manages event subscriptions for SUBSCRIBE/UNSUBSCRIBE. 4. Agent Lifecycle and Trust States An agent announces itself with DISCOVER. The manager validates the identity, profile, authentication material, and any pre-registration data before assigning a trust state. The following trust states are defined: discovered The agent has announced itself, but has not yet been evaluated. pending The manager is aware of the agent and awaits a trust decision. trusted The manager has accepted the agent. This is a prerequisite for management operations, but does not automatically enable CONFIG or EXEC. quarantined The agent is isolated for read-only observation or investigation. rejected The manager refuses the agent. offline The agent is known, but is not currently reachable. stale The agent has missed expected heartbeats beyond the configured threshold. revoked The manager has explicitly revoked trust. 4.1. Trust Transitions Trust transitions are controlled by the manager. Agents MUST NOT self-promote to trusted. The following transitions are normative: Efstathiou Expires 18 February 2027 [Page 9] Internet-Draft SAMP August 2026 * discovered to pending: Manager begins evaluation. * pending to trusted: Manager approves the agent. * pending to rejected: Manager refuses the agent. * pending to quarantined: Manager isolates for investigation. * trusted to quarantined: Manager isolates a previously trusted agent. * trusted to revoked: Manager revokes trust. * trusted to offline: Agent becomes unreachable. * offline to trusted: Agent returns and re-authenticates. * offline to stale: Agent has been offline beyond the stale threshold. * stale to revoked: Manager gives up on the agent. * Any state to revoked: Manager explicitly revokes. CONFIG and EXEC MUST NOT be accepted before trusted state is established. QUERY and PUSH MAY be accepted from quarantined agents at manager discretion. 4.2. Enrollment Enrollment is the process by which a manager evaluates an announced agent and assigns an initial trust state. SAMP v0.1 supports the following enrollment methods: Manual approval The manager operator manually approves or rejects each discovered agent. Pre-shared token The agent includes a pre-shared enrollment token in its DISCOVER payload. The manager validates the token against a pre-registration list. Public key thumbprint The agent includes a public key or thumbprint in its DISCOVER payload. The manager validates it against a pre- registration list. This method is preparatory for future per- agent public key signing. The enrollment method is a manager-side policy decision. The agent supplies authentication material; the manager decides. Efstathiou Expires 18 February 2027 [Page 10] Internet-Draft SAMP August 2026 4.3. Agent Bootstrap and Manager Location Agents need to locate a manager before sending DISCOVER. SAMP v0.1 supports the following bootstrap methods: Configuration file The agent reads the manager URL from a local configuration file. Environment variable The agent reads the manager URL from an environment variable. Command-line argument The agent receives the manager URL as a startup argument. DNS SRV record The agent resolves a DNS SRV record to discover the manager endpoint. Manager pre-provisioning The manager URL is pre-provisioned in the agent's deployment environment (e.g., container orchestration config). Manual specification The operator manually provides the manager URL at agent startup. Bootstrap method selection is an implementation decision. The protocol does not mandate a specific bootstrap mechanism. 5. SAMP Profile A SAMP Profile describes the agent as a managed entity. It includes: * *Identity fields*: agent_id, agent_version, profile_version, agent_type, autonomy_class, and optional framework metadata. * *Categories and fields*: Named groups of exposed state or configuration fields. * *Capabilities*: Event subscriptions, executable commands, or other advertised capabilities. * *Policy declarations*: exec_policy and config_policy controlling CONFIG and EXEC behavior. * *Implementation metadata*: Fields needed by the manager for registration and registry maintenance. Efstathiou Expires 18 February 2027 [Page 11] Internet-Draft SAMP August 2026 5.1. Required Identity Fields The following fields MUST be present in every SAMP Profile: +=================+========+=============================+ | Field | Type | Description | +=================+========+=============================+ | agent_id | string | Unique agent identifier | +-----------------+--------+-----------------------------+ | name | string | Human-readable agent name | +-----------------+--------+-----------------------------+ | agent_version | string | Agent software version | +-----------------+--------+-----------------------------+ | profile_version | string | SAMP profile schema version | +-----------------+--------+-----------------------------+ | agent_type | string | Framework type (e.g., | | | | openclaw, hermes, custom) | +-----------------+--------+-----------------------------+ | autonomy_class | string | Autonomy classification | | | | (see Section 6) | +-----------------+--------+-----------------------------+ Table 2: Required Profile Identity Fields 5.2. Category and Field Model A profile organizes exposed data into categories. Each category contains named fields with declared types. Supported field types in SAMP v0.1: Efstathiou Expires 18 February 2027 [Page 12] Internet-Draft SAMP August 2026 +===========+================================+ | Type | JSON representation | +===========+================================+ | string | JSON string | +-----------+--------------------------------+ | int | JSON number (integer) | +-----------+--------------------------------+ | float | JSON number | +-----------+--------------------------------+ | boolean | JSON boolean | +-----------+--------------------------------+ | timestamp | JSON string in RFC 3339 format | +-----------+--------------------------------+ | object | JSON object | +-----------+--------------------------------+ | array | JSON array | +-----------+--------------------------------+ Table 3: Profile Field Types 5.3. Minimal Required Category Every profile MUST include a system category with at least the following fields: +==================+===========+====================================+ | Field | Type | Description | +==================+===========+====================================+ | system.status | string | Current operational status | +------------------+-----------+------------------------------------+ | system.uptime | int | Uptime in seconds | +------------------+-----------+------------------------------------+ | system.version | string | Agent software version | +------------------+-----------+------------------------------------+ | system.last_seen | timestamp | Last heartbeat or | | | | interaction time | +------------------+-----------+------------------------------------+ Table 4: Required System Category Fields 5.4. Profile Validation Managers MUST validate a profile before trusting an agent. Validation includes: * Presence of all required identity fields. * Presence of the system category with all required fields. Efstathiou Expires 18 February 2027 [Page 13] Internet-Draft SAMP August 2026 * Valid autonomy_class value (see Section 6). * Valid field type declarations. * Presence and validity of policy declarations if CONFIG or EXEC capabilities are advertised. Managers MUST NOT fetch arbitrary external profile URLs from untrusted DISCOVER payloads. Profiles SHOULD be sent inline or retrieved only from manager-approved locations. 5.5. Profile Format Profiles are authored as TOML in SAMP version 0.1 for human readability. Implementations MAY represent the profile internally as structured JSON or another equivalent data model. The on-the-wire encoding of profile data in SAMP PDUs is JSON. 6. Autonomy Classes Every SAMP Agent declares an autonomy_class in its profile. The following initial classes are defined: advisory Read-only observation and reporting only. Agent does not accept CONFIG or EXEC. operational-readonly Observation and limited local or self- configuration. No execution. operational-write Configuration is allowed. Execution is limited to an explicit allow-list defined in the profile. critical-write Configuration and execution are allowed only under strict policy. The autonomy class is an input to policy. It MUST NOT grant permission by itself. Manager policy remains authoritative. An agent with advisory autonomy class SHOULD NOT advertise CONFIG or EXEC capabilities. A manager SHOULD reject CONFIG or EXEC attempts targeting an advisory agent. 7. Protocol Operations SAMP version 0.1 defines the following PDU types: PING Agent-to-manager heartbeat. The manager responds with a PING response (a PING PDU with direction: "response"). Efstathiou Expires 18 February 2027 [Page 14] Internet-Draft SAMP August 2026 DISCOVER Agent-to-manager self-announcement and profile advertisement. The manager responds with DISCOVER_ACK. DISCOVER_ACK Manager response to DISCOVER, including the assigned trust state and optional manager-assigned metadata. QUERY Manager-to-agent request for state, metadata, or profile fields. The agent responds with a QUERY PDU with direction: "response". PUSH Agent-to-manager asynchronous event notification. No response is expected unless the manager explicitly requests acknowledgment. SUBSCRIBE Manager-to-agent request to subscribe to an event stream. The agent responds with a subscription_id. UNSUBSCRIBE Manager-to-agent request to cancel a subscription. CONFIG Manager-to-agent configuration change. The agent responds with success or error. EXEC Manager-to-agent request to execute an explicitly exposed operation. The agent responds with a result or error. 7.1. PDU Directions Each PDU has a direction field indicating its role: +==============+==================================+ | Direction | Meaning | +==============+==================================+ | request | Initiates an operation | +--------------+----------------------------------+ | response | Responds to a request | +--------------+----------------------------------+ | notification | Unsolicited asynchronous message | +--------------+----------------------------------+ | error | Error response to a request | +--------------+----------------------------------+ Table 5: PDU Directions Efstathiou Expires 18 February 2027 [Page 15] Internet-Draft SAMP August 2026 7.2. PDU Exchange Patterns +=============+===================================+===========+ | PDU Type | Pattern | Initiator | +=============+===================================+===========+ | PING | request - response | Agent | +-------------+-----------------------------------+-----------+ | DISCOVER | request - response (DISCOVER_ACK) | Agent | +-------------+-----------------------------------+-----------+ | QUERY | request - response | Manager | +-------------+-----------------------------------+-----------+ | PUSH | notification (no response) | Agent | +-------------+-----------------------------------+-----------+ | SUBSCRIBE | request - response | Manager | +-------------+-----------------------------------+-----------+ | UNSUBSCRIBE | request - response | Manager | +-------------+-----------------------------------+-----------+ | CONFIG | request - response | Manager | +-------------+-----------------------------------+-----------+ | EXEC | request - response | Manager | +-------------+-----------------------------------+-----------+ Table 6: PDU Exchange Patterns 7.3. Authentication Requirements by PDU All PDUs exchanged between a manager and an agent MUST be authenticated when authentication is enabled. See Section 9 for details. 7.4. DISCOVER Rate Limiting Managers SHOULD rate-limit DISCOVER messages from unknown agents to prevent discovery flooding. A manager MAY maintain a pending-agent quota and reject excess discoveries with a rate_limited error. 7.5. SUBSCRIBE and UNSUBSCRIBE Semantics When a manager sends SUBSCRIBE, the agent allocates a subscription and returns a subscription_id in the response. Subsequent PUSH PDUs related to that subscription include the subscription_id in the envelope. Subscriptions have a manager-defined or agent-defined time-to-live (TTL). A subscription that is not renewed within its TTL expires automatically. Managers SHOULD renew subscriptions before expiry. Efstathiou Expires 18 February 2027 [Page 16] Internet-Draft SAMP August 2026 UNSUBSCRIBE cancels an active subscription. The agent stops sending PUSH PDUs for the cancelled subscription. Subscription persistence across agent restarts is NOT required in SAMP v0.1. Subscriptions do not survive agent reconnect unless the agent implementation explicitly supports persistence. 8. Message Format All SAMP messages use a common PDU envelope encoded as UTF-8 JSON [RFC8259] in SAMP version 0.1. 8.1. Common PDU Envelope The following table defines the envelope fields: Efstathiou Expires 18 February 2027 [Page 17] Internet-Draft SAMP August 2026 +=================+========+=============+========================+ | Field | Type | Presence | Description | +=================+========+=============+========================+ | version | string | Required | Protocol version, | | | | | e.g., "0.1" | +-----------------+--------+-------------+------------------------+ | type | string | Required | PDU type (see | | | | | Section 7) | +-----------------+--------+-------------+------------------------+ | direction | string | Required | One of request, | | | | | response, | | | | | notification, error | +-----------------+--------+-------------+------------------------+ | agent_id | string | Required | Identifier of the | | | | | managed agent | +-----------------+--------+-------------+------------------------+ | timestamp | string | Required | UTC timestamp in RFC | | | | | 3339 format [RFC3339] | +-----------------+--------+-------------+------------------------+ | request_id | string | Required | UUID for correlation | | | | | and replay protection | | | | | [RFC9562] | +-----------------+--------+-------------+------------------------+ | payload | object | Required | PDU-specific JSON | | | | | object. Empty | | | | | payloads encode as {}. | +-----------------+--------+-------------+------------------------+ | signature | string | Conditional | HMAC-SHA256 signature | | | | | (see Section 9). | | | | | Required when | | | | | authentication is | | | | | enabled. | +-----------------+--------+-------------+------------------------+ | sequence | int | Optional | Sequence number for | | | | | ordered streams | +-----------------+--------+-------------+------------------------+ | subscription_id | string | Optional | Subscription | | | | | identifier for | | | | | SUBSCRIBE/UNSUBSCRIBE/ | | | | | PUSH | +-----------------+--------+-------------+------------------------+ Table 7: Common PDU Envelope Fields 8.1.1. Field Validation Rules * version MUST be "0.1" for this version of the protocol. Efstathiou Expires 18 February 2027 [Page 18] Internet-Draft SAMP August 2026 * type MUST be one of the PDU types listed in Section 7, expressed in lowercase (e.g., "ping", "discover", "query"). * direction MUST be one of request, response, notification, error. * agent_id MUST be a non-empty string. * timestamp MUST be a valid RFC 3339 UTC timestamp with timezone designator Z. * request_id MUST be a valid UUID as defined by [RFC9562]. Implementations SHOULD use UUID version 4 or another version with equivalent uniqueness properties. * payload MUST be a JSON object. Empty payloads are encoded as {}. * Unknown envelope fields MUST be ignored by receivers. This ensures forward compatibility. * Unknown PDU types MUST return an unknown_type error. 8.1.2. Request/Response Correlation A response or error PDU MUST include the same request_id as the request it corresponds to. This allows both parties to correlate requests and responses without relying on transport-level correlation. 8.1.3. Timestamp Validation Receivers SHOULD validate that timestamps are within an acceptable clock skew window (e.g., plus or minus 300 seconds). PDUs with timestamps outside the window SHOULD be rejected with a replay_detected error when replay protection is enabled. 8.1.4. Sequence Numbers The sequence field is OPTIONAL. When present, it provides ordering for streams of PDUs (e.g., subscription event streams). Sequence numbers are per-subscription and start at 1. Receivers MAY detect gaps but MUST NOT reject PDUs solely for sequence gaps in SAMP v0.1. 8.2. PDU-Specific Payloads 8.2.1. PING Request payload: Efstathiou Expires 18 February 2027 [Page 19] Internet-Draft SAMP August 2026 {} Response payload: {"status": "operational"} The status field in the response is a free-form string indicating the agent's self-reported status (e.g., "operational", "degraded"). 8.2.2. DISCOVER Request payload: { "profile": { /* full SAMP Profile object */ }, "endpoint": "https://agent.example/samp", "capabilities": ["query", "push", "exec"] } The profile field contains the full SAMP Profile. The endpoint field contains the agent's SAMP endpoint URL. The capabilities array lists the PDU operations the agent supports. Response (DISCOVER_ACK) payload: { "state": "trusted", "manager_version": "0.1", "assigned_id": "agent-001" } The state field contains the manager-assigned trust state. The manager_version field contains the manager's SAMP version. The assigned_id field is optional and MAY be used when the manager assigns or overrides the agent identifier. If enrollment is rejected, the response payload contains: { "state": "rejected", "reason": "profile_invalid" } 8.2.3. QUERY Request payload: Efstathiou Expires 18 February 2027 [Page 20] Internet-Draft SAMP August 2026 { "fields": ["system.status", "system.uptime", "model.primary"] } The fields array contains one or more dotted-path field identifiers from the agent's profile categories. The agent returns values for fields it supports and reports unknown_field for unsupported fields. Response payload: { "values": { "system.status": "operational", "system.uptime": 86400 }, "unknown": ["model.primary"] } The values object contains the resolved field values. The unknown array lists requested fields that the agent does not expose. If all requested fields are unknown, the response is an error with code unknown_field. 8.2.4. PUSH Notification payload: { "event": "status_change", "data": { "old_status": "operational", "new_status": "degraded" }, "category": "system" } The event field is the event type. The data field is an arbitrary JSON object with event-specific content. The category field indicates the profile category the event relates to. PUSH PDUs use direction: "notification". No response is expected unless the manager explicitly requests acknowledgment. 8.2.5. SUBSCRIBE Request payload: Efstathiou Expires 18 February 2027 [Page 21] Internet-Draft SAMP August 2026 { "event_types": ["status_change", "alert"], "category": "system", "ttl_seconds": 300 } The event_types array filters the subscription to specific event types. An empty array or omitted field subscribes to all events in the specified category. The ttl_seconds field requests a subscription time-to-live. Response payload: { "subscription_id": "sub-abc123", "ttl_seconds": 300, "renew_before": "2026-08-14T09:05:00Z" } 8.2.6. UNSUBSCRIBE Request payload: {"subscription_id": "sub-abc123"} Response payload: {"cancelled": true} 8.2.7. CONFIG Request payload: { "fields": { "model.fallback": "kimi-k2.6", "system.log_level": "debug" }, "scope": "agent" } The fields object contains the configuration key-value pairs to apply. Keys are dotted-path identifiers. The scope field is either "agent" (agent-wide) or "session" (current session only). The default scope is "agent". Response payload: Efstathiou Expires 18 February 2027 [Page 22] Internet-Draft SAMP August 2026 { "applied": ["model.fallback", "system.log_level"], "rejected": [] } The applied array lists fields that were successfully changed. The rejected array lists fields that were rejected, with optional reasons: { "applied": ["system.log_level"], "rejected": [ {"field": "model.fallback", "reason": "read_only"} ] } CONFIG is disabled unless explicitly supported by the agent profile and allowed by manager policy. The agent MUST validate each field against its profile-declared writable fields. 8.2.8. EXEC Request payload: { "command": "session_reset", "params": { "session_id": "sess-001" } } The command field names an executable operation from the agent's profile exec_policy.allowed_commands. The params object contains typed parameters matching the command's declared schema. Response payload: { "result": "success", "output": { "reset": true } } If the command is rejected, the response contains: Efstathiou Expires 18 February 2027 [Page 23] Internet-Draft SAMP August 2026 { "result": "exec_disabled", "detail": "EXEC is not enabled for this agent" } EXEC is disabled by default. It MUST be explicitly enabled per agent and per command in the profile. Parameters MUST have typed schemas; free-form arguments are not allowed. 8.3. Error Envelope When an error occurs, the response PDU has direction: "error" and the payload contains an error object: { "version": "0.1", "type": "query", "direction": "error", "agent_id": "agent-001", "timestamp": "2026-08-14T09:00:01Z", "request_id": "24f8587c-4c4b-4e41-9f47-222c0f5f8b8b", "payload": { "error": { "code": "unknown_field", "detail": "Field 'model.primary' is not exposed", "timestamp": "2026-08-14T09:00:01Z" } } } The error payload object has the following fields: +===========+========+==========+==================================+ | Field | Type | Presence | Description | +===========+========+==========+==================================+ | code | string | Required | Error code (see Section 8.4) | +-----------+--------+----------+----------------------------------+ | detail | string | Optional | Human-readable error detail | +-----------+--------+----------+----------------------------------+ | timestamp | string | Required | UTC timestamp in RFC 3339 format | +-----------+--------+----------+----------------------------------+ Table 8: Error Payload Fields 8.4. Error Codes The following error codes are defined for SAMP v0.1: Efstathiou Expires 18 February 2027 [Page 24] Internet-Draft SAMP August 2026 +=====================+========================================+ | Code | Description | +=====================+========================================+ | malformed_pdu | The PDU is not valid JSON or is | | | missing required envelope fields | +---------------------+----------------------------------------+ | unknown_type | The PDU type is not recognized | +---------------------+----------------------------------------+ | invalid_value | A field value is invalid (e.g., wrong | | | type, out of range) | +---------------------+----------------------------------------+ | schema_mismatch | The payload does not match the | | | expected schema for the PDU type | +---------------------+----------------------------------------+ | version_unsupported | The protocol version is not supported | +---------------------+----------------------------------------+ | profile_invalid | The profile is missing required fields | | | or is otherwise invalid | +---------------------+----------------------------------------+ | auth_failed | Authentication failed (missing or | | | invalid signature) | +---------------------+----------------------------------------+ | replay_detected | The request_id was previously seen | | | with different request content, or the | | | PDU violates the replay-window policy | +---------------------+----------------------------------------+ | unknown_field | A requested field is not exposed by | | | the agent | +---------------------+----------------------------------------+ | exec_disabled | EXEC is not enabled for this agent or | | | command | +---------------------+----------------------------------------+ | config_disabled | CONFIG is not enabled for this agent | +---------------------+----------------------------------------+ | policy_denied | Manager policy denies the requested | | | operation | +---------------------+----------------------------------------+ | rate_limited | The receiver is rate-limiting requests | +---------------------+----------------------------------------+ | back_pressure | The receiver is overloaded and cannot | | | process the request | +---------------------+----------------------------------------+ | bootstrap_failed | Agent bootstrap or enrollment failed | +---------------------+----------------------------------------+ | internal_error | An internal error occurred on the | | | receiver side | +---------------------+----------------------------------------+ Efstathiou Expires 18 February 2027 [Page 25] Internet-Draft SAMP August 2026 Table 9: SAMP Error Codes 8.5. JSON Encoding Requirements * All SAMP JSON MUST be encoded as UTF-8 [RFC8259]. * Implementations MUST NOT include byte-order marks (BOM). * Implementations MUST NOT use non-standard JSON extensions (e.g., trailing commas, comments). * Field names in the envelope and in defined payloads are lowercase with underscores (e.g., request_id, agent_id). * Timestamps MUST use RFC 3339 UTC format with the Z designator [RFC3339]. * UUIDs MUST be in canonical string form [RFC9562]. * Unknown envelope fields MUST be ignored (forward compatibility). * Unknown PDU types MUST return unknown_type error. 8.6. Behavior for Unknown Fields and Unknown PDU Types * Unknown envelope fields: MUST be ignored. This enables forward compatibility. * Unknown PDU types: MUST return an unknown_type error. * Unknown payload fields within a known PDU type: MUST be ignored, unless the PDU type explicitly defines strict validation. * Unknown profile fields: MUST be ignored by the manager during validation, but SHOULD be logged. 9. Authentication SAMP v0.1 uses shared-secret authentication with HMAC-SHA256 [RFC2104] [RFC6234]. 9.1. Authentication Model SAMP distinguishes between: * *Mandatory implementation support*: All conformant SAMP v0.1 implementations MUST support HMAC-SHA256 message authentication. Efstathiou Expires 18 February 2027 [Page 26] Internet-Draft SAMP August 2026 * *Mandatory deployment use*: Deployments on non-localhost networks MUST enable authentication and MUST use HTTPS for transport confidentiality. * *Localhost/lab exception*: Authentication MAY be disabled for loopback (127.0.0.1/localhost) development and testing only. * *Message authentication*: HMAC-SHA256 over the canonical form of the PDU (see Section 9.4). * *Transport confidentiality*: Provided by TLS 1.3 [RFC8446] for HTTPS. SAMP does not define its own transport encryption. * *Authorization policy*: Enforced by the manager based on trust state, autonomy class, and local policy. Authentication is a prerequisite for authorization, not a substitute. 9.2. HMAC-SHA256 Signing When authentication is enabled: 1. The sender computes a canonical JSON representation of the PDU (see Section 9.4). 2. The sender computes HMAC-SHA256 over the canonical bytes using the shared secret. 3. The resulting signature is placed in the signature envelope field as a lowercase hex-encoded string. 4. The receiver recomputes the HMAC over the canonical form (excluding the signature field) and compares it to the received signature. 5. If the signature is missing or does not match, the receiver returns an auth_failed error. 9.3. Key Identification SAMP v0.1 uses a single shared secret per manager-agent pair. Key identification (e.g., key IDs) is not defined in v0.1. Future versions MAY introduce key identification for multi-key support. Key distribution is out of band. Implementations SHOULD store shared secrets in a secrets manager, not in plaintext configuration files. Efstathiou Expires 18 February 2027 [Page 27] Internet-Draft SAMP August 2026 9.4. Canonical JSON SAMP v0.1 uses the JSON Canonicalization Scheme (JCS) defined in [RFC8785] for computing HMAC signatures. 9.4.1. Canonicalization Procedure 1. Take the PDU as a JSON object. 2. Remove the signature field from the object. 3. Apply RFC 8785 canonicalization to the resulting object: Sort object keys lexicographically (as defined by RFC 8785); serialize numbers according to RFC 8785 rules; escape strings according to RFC 8785 rules; remove insignificant whitespace. 4. Encode the canonical string as UTF-8. 5. Compute HMAC-SHA256 over the UTF-8 bytes. 9.4.2. Signature Representation The signature field contains the lowercase hex-encoded HMAC-SHA256 digest. Example signature value: a1b2c3d4e5f6... (64 hex characters). 9.4.3. Verification Procedure 1. Extract the signature field from the received PDU. 2. Remove the signature field from the PDU object. 3. Apply RFC 8785 canonicalization to the modified object. 4. Encode as UTF-8. 5. Compute HMAC-SHA256 using the shared secret. 6. Compare the computed digest with the received signature using a constant-time comparison. 7. If they match, authentication succeeds. If not, return auth_failed. 9.4.4. Failure Behavior Efstathiou Expires 18 February 2027 [Page 28] Internet-Draft SAMP August 2026 * Missing signature field when authentication is enabled: auth_failed error. * Invalid signature: auth_failed error. * Malformed signature (not a valid hex string): auth_failed error. 9.4.5. Unicode Normalization SAMP does not apply Unicode normalization during signing or verification. JSON strings are preserved exactly as they appear in the PDU object. The sender MUST NOT modify or normalize JSON string values before applying JCS canonicalization. The receiver MUST NOT modify or normalize JSON string values before verifying the signature. Different Unicode code-point sequences produce different canonical bytes and therefore different HMAC signatures. If an implementation needs a specific normalization form (e.g., NFC) for application-level consistency, it MUST apply normalization before constructing the PDU object, not as a signing step. 10. Transport Mapping SAMP defines protocol semantics and message envelopes independently from the underlying transport. 10.1. HTTP Transport SAMP v0.1 requires HTTP [RFC9110] as the baseline transport. 10.1.1. HTTP Method All SAMP PDUs are sent as HTTP POST requests with a JSON body containing the PDU envelope. Responses are returned in the HTTP response body. For agent-to-manager PDUs (PING, DISCOVER, PUSH), the agent sends an HTTP POST to the manager's SAMP endpoint. For manager-to-agent PDUs (QUERY, CONFIG, EXEC, SUBSCRIBE, UNSUBSCRIBE), the manager sends an HTTP POST to the agent's SAMP endpoint. 10.1.2. Content-Type The Content-Type header MUST be application/json. Efstathiou Expires 18 February 2027 [Page 29] Internet-Draft SAMP August 2026 10.1.3. Endpoint Path Implementations MAY choose any endpoint path. The agent's SAMP endpoint URL is advertised in the DISCOVER payload's endpoint field. The manager's SAMP endpoint URL is configured during agent bootstrap. Recommended conventional paths: Manager: POST /samp (accepts all PDU types); Agent: POST /samp (accepts all PDU types). 10.1.4. HTTP Status Codes SAMP uses HTTP status codes as follows: +===========================+===================================+ | HTTP Status | Meaning | +===========================+===================================+ | 200 OK | Successful request or response | +---------------------------+-----------------------------------+ | 400 Bad Request | Malformed PDU or invalid JSON | +---------------------------+-----------------------------------+ | 401 Unauthorized | Authentication failed | +---------------------------+-----------------------------------+ | 403 Forbidden | Policy denied | +---------------------------+-----------------------------------+ | 404 Not Found | Unknown agent or endpoint | +---------------------------+-----------------------------------+ | 409 Conflict | Replay detected or state conflict | +---------------------------+-----------------------------------+ | 429 Too Many Requests | Rate limited | +---------------------------+-----------------------------------+ | 500 Internal Server Error | Internal error | +---------------------------+-----------------------------------+ | 503 Service Unavailable | Back-pressure or overload | +---------------------------+-----------------------------------+ Table 10: HTTP Status Code Mapping The SAMP error envelope in the response body provides the precise error code. The HTTP status code is a transport-level indicator; the SAMP error code is authoritative. 10.1.5. HTTPS Requirements * Plain HTTP is suitable ONLY for localhost (127.0.0.1) development and testing. It MUST NOT be used for non-localhost deployments. * HTTPS is REQUIRED for all non-localhost deployments, including isolated management networks. Efstathiou Expires 18 February 2027 [Page 30] Internet-Draft SAMP August 2026 * TLS 1.3 [RFC8446] is RECOMMENDED. TLS 1.2 MAY be used for compatibility but TLS 1.3 is preferred. * Certificate validation MUST be enforced for HTTPS connections. Disabling certificate validation is NOT RECOMMENDED outside development. 10.2. WebSocket Transport WebSocket support is OPTIONAL in SAMP v0.1. WebSocket is primarily useful for: * Persistent event streams (subscription delivery). * Frequent heartbeats (reducing HTTP overhead). * Bidirectional communication without polling. When WebSocket is used: * The connection upgrade follows the WebSocket protocol [RFC6455]. * SAMP PDUs are sent as WebSocket text frames containing the JSON envelope. * The same PDU envelope format and authentication rules apply. * A WebSocket connection does not change the request-response semantics of individual PDUs. WebSocket transport is NOT required for any conformance tier in v0.1. 10.3. Retry and Backoff Implementations MAY retry failed requests with exponential backoff. Retries of the same request MUST use the same request_id as the original attempt. The receiver SHOULD cache the request digest and the corresponding response for a limited time period. The request digest is SHA-256 over the RFC 8785 canonical bytes of the PDU with the signature field removed. This is the same canonicalization used for HMAC signing (see Section 9.4), with the addition of a SHA-256 hash over the canonical bytes. * If the receiver sees the same request_id with the same request digest, it returns the cached response without re-executing the operation. Efstathiou Expires 18 February 2027 [Page 31] Internet-Draft SAMP August 2026 * If the receiver sees the same request_id with a different request digest, it rejects the PDU with a replay_detected error. Non-idempotent operations, especially EXEC, SHOULD NOT be retried unless the receiver supports safe cached-response behavior for that operation type. 11. Conformance SAMP version 0.1 defines four conformance tiers: SAMP-Observe Supports PING, DISCOVER, DISCOVER_ACK, QUERY, and PUSH. Does not send CONFIG or EXEC. SAMP-Subscribe Supports SAMP-Observe plus SUBSCRIBE and UNSUBSCRIBE. SAMP-Configure Supports SAMP-Subscribe plus CONFIG. SAMP-Execute Supports SAMP-Configure plus EXEC. 11.1. Mandatory Implementation Requirements All tiers MUST support: * JSON encoding [RFC8259]. * HTTP transport. * Profile parsing and validation. * HMAC-SHA256 authentication support (implementation MUST support it; deployment MAY disable it for localhost only). * Standard error envelopes and error codes. * PDU envelope parsing with all required fields. 11.2. Conformance Testing Implementations claiming a conformance tier SHOULD be validated against a test suite covering: * All required PDUs for the claimed tier. * Profile validation. * Authentication (enable/disable, valid/invalid signatures). Efstathiou Expires 18 February 2027 [Page 32] Internet-Draft SAMP August 2026 * Error handling for all defined error codes. * HTTP transport compliance. A reference test suite is planned but not yet available. Implementers SHOULD publish interoperability test results. 12. Security Considerations 12.1. Threat Model SAMP v0.1 is designed for controlled environments. The following threats are identified: 12.1.1. Rogue Managers A rogue manager could send unauthorized QUERY, CONFIG, or EXEC PDUs to an agent. Mitigations in v0.1: * Agents SHOULD maintain an allow-list of authorized manager addresses. * Agents MUST validate HMAC signatures. * Agents MUST reject CONFIG and EXEC from untrusted or unauthorized managers. Future: Per-agent public key authentication and mTLS. 12.1.2. Rogue Agents A rogue agent could announce itself with DISCOVER and provide false profile information. Mitigations in v0.1: * Managers MUST validate profiles before trusting. * Managers SHOULD use pre-registration or enrollment tokens. * Managers SHOULD rate-limit DISCOVER from unknown agents. Future: Signed profiles and certificate-based identity. Efstathiou Expires 18 February 2027 [Page 33] Internet-Draft SAMP August 2026 12.1.3. Credential Theft The shared secret used for HMAC authentication could be stolen. Mitigations in v0.1: * Shared secrets SHOULD be stored in a secrets manager. * Secrets SHOULD be distributed out of band. * Secrets SHOULD be rotated periodically. Future: Per-agent public key authentication (Ed25519). 12.1.4. Replay Attacks An attacker could capture and replay a valid PDU. Mitigations in v0.1: * request_id and request digest checked against a replay cache. The request digest is SHA-256 over the RFC 8785 canonical bytes of the PDU with the signature field removed. Same request_id with same digest returns cached response; same request_id with different digest is rejected as replay_detected. * Timestamp validation with clock-skew window. * Replay cache is REQUIRED for CONFIG and EXEC operations. * Replay cache is RECOMMENDED for all authenticated PDUs. Limitations: Replay cache is in-memory in v0.1; persistence is future work. Cache size is implementation-defined. 12.1.5. Profile Spoofing An agent could advertise a profile with false capabilities or autonomy class to gain elevated permissions. Mitigations in v0.1: * Autonomy class does not grant permission; manager policy is authoritative. * CONFIG and EXEC require explicit profile exposure AND manager policy authorization. Efstathiou Expires 18 February 2027 [Page 34] Internet-Draft SAMP August 2026 * Managers SHOULD cross-check advertised capabilities against pre- registration data. 12.1.6. Unauthorized CONFIG and EXEC A manager with valid credentials could send unauthorized CONFIG or EXEC to an agent. Mitigations in v0.1: * EXEC is disabled by default. * CONFIG and EXEC require explicit profile exposure. * Agents SHOULD enforce local policy in addition to manager policy. * EXEC parameters MUST have typed schemas; free-form arguments are not allowed. * exec_policy in the profile MAY define: allowed_commands, dangerous_commands, require_ack, cooldown, max_per_minute, scope, and audit fields. 12.1.7. Version Downgrade An attacker could attempt to force use of a weaker protocol version. Mitigations in v0.1: * v0.1 is the only defined version. * Receivers MUST reject unsupported versions with version_unsupported. * Future versions MUST define backward compatibility rules. 12.1.8. Event and Discovery Flooding An agent could flood a manager with PUSH events or DISCOVER messages. Mitigations in v0.1: * Managers SHOULD rate-limit DISCOVER from unknown agents. * Managers MAY apply back-pressure with rate_limited or back_pressure errors. * Managers MAY maintain a pending-agent quota. Efstathiou Expires 18 February 2027 [Page 35] Internet-Draft SAMP August 2026 12.1.9. Registry Poisoning A rogue agent could attempt to overwrite or evict legitimate agent entries in the manager's registry. Mitigations in v0.1: * Registry updates require successful authentication. * DISCOVER from unauthenticated agents MUST NOT modify the registry beyond creating a discovered or pending entry. 12.2. Audit Requirements Implementations SHOULD log all CONFIG and EXEC operations, including: Timestamp, Agent ID, Manager ID (if identifiable), Operation details (field changes, command, parameters), and Result (success/failure). Audit logs SHOULD be tamper-evident and stored separately from the system being managed. 12.3. Rate Limiting and Back-Pressure Managers and agents SHOULD implement rate limiting for incoming PDUs. Rate limiting MAY be applied per-agent, per-PDU-type, or globally. Excess requests SHOULD be rejected with rate_limited or back_pressure errors. 12.4. Trust Bootstrap The initial trust establishment between a manager and an agent is a critical moment. SAMP v0.1 supports: Manual approval by the operator, Pre-shared enrollment tokens, and Public key thumbprint matching. Future versions MAY support certificate-based enrollment and automated trust establishment. 12.5. Token Rotation and Storage Shared secrets SHOULD be rotated periodically. Rotation frequency is a deployment decision. Tokens SHOULD be stored in a secrets manager (e.g., HashiCorp Vault, AWS Secrets Manager) rather than plaintext files. Token rotation in v0.1 requires out-of-band coordination between the manager and agent. Automated rotation is future work. Efstathiou Expires 18 February 2027 [Page 36] Internet-Draft SAMP August 2026 12.6. Summary: Current Requirements vs Future Work +================+==========================+======================+ | Threat | v0.1 Mitigation | Future Enhancement | +================+==========================+======================+ | Rogue managers | Manager allow-list, HMAC | mTLS, per-agent keys | +----------------+--------------------------+----------------------+ | Rogue agents | Profile validation, | Signed profiles, | | | enrollment | cert identity | +----------------+--------------------------+----------------------+ | Credential | Secrets manager, | Per-agent Ed25519 | | theft | rotation | keys | +----------------+--------------------------+----------------------+ | Replay | request_id cache, | Persistent cache, | | | timestamp | sequence validation | +----------------+--------------------------+----------------------+ | Profile | Manager policy | Signed profiles | | spoofing | authoritative | | +----------------+--------------------------+----------------------+ | Unauthorized | Disabled by default, | RBAC, OPA | | EXEC/CONFIG | policy | integration | +----------------+--------------------------+----------------------+ | Version | Reject unsupported | Version negotiation | | downgrade | versions | | +----------------+--------------------------+----------------------+ | Flooding | Rate limiting, back- | Flow-control | | | pressure | protocol | +----------------+--------------------------+----------------------+ | Registry | Auth-required updates | Signed registrations | | poisoning | | | +----------------+--------------------------+----------------------+ Table 11: Security Mitigations: v0.1 vs Future 13. Privacy Considerations 13.1. Sensitive Metadata Exposure SAMP profiles and query responses can expose sensitive information about an agent, including: Framework details and version, Model names and provider information, Configuration values, Active sessions, Tool availability, Memory backends, Operational state, and Uptime and availability patterns. Managers and agents SHOULD minimize exposed fields. Profiles SHOULD include only fields necessary for management. QUERY responses SHOULD not include secrets, credentials, prompt contents, private user data, or tool outputs unless explicitly required and authorized. Efstathiou Expires 18 February 2027 [Page 37] Internet-Draft SAMP August 2026 13.2. Event Data Sensitivity PUSH events can contain operationally sensitive information, including: Status changes revealing operational patterns, Error details exposing internal architecture, Performance metrics revealing capacity or load, and Configuration changes revealing business logic. Operators SHOULD classify and filter events before exporting them to telemetry, logging, or ticketing systems. Events containing user data MUST be handled according to applicable data protection regulations. 13.3. Data Minimization Agents SHOULD expose the minimum profile data necessary for management. Managers SHOULD query only the fields they need. Bulk profile export or full-state queries SHOULD be restricted to authorized operators. 13.4. Log Protection SAMP audit logs and event stores may contain sensitive operational data. Logs SHOULD be: Access-controlled, Retained according to a defined policy, Protected against tampering, and Sanitized before sharing or export. 14. Operational Considerations 14.1. Network Placement SAMP deployments SHOULD place managers and agents on a dedicated management network or equivalent restricted trust boundary. Firewall rules SHOULD limit SAMP traffic to known managers and agents. Agents SHOULD maintain an allow-list of authorized manager addresses. Managers SHOULD maintain an allow-list or pre-registration registry for expected agents. 14.2. Scaling SAMP v0.1 targets single-agent interactions. A single manager MAY manage multiple agents, but fleet-scale bulk operations are not defined in v0.1. Deployments needing fleet-scale operations SHOULD use external orchestration (e.g., scripts, configuration management) layered on top of SAMP. Scaling approaches compatible with v0.1: Efstathiou Expires 18 February 2027 [Page 38] Internet-Draft SAMP August 2026 * *HTTP-only polling*: Agents are polled by the manager at intervals. Suitable for moderate agent counts. * *Hierarchical managers*: A tier of intermediate managers collects from agents and reports to a central manager. Requires out-of- band coordination. * *Queue-based ingestion*: PUSH events are sent to a message queue rather than directly to the manager. Requires agent-side queue configuration. Federation, multi-manager conflict resolution, and transactional configuration are future work. 14.3. Observability SAMP management traffic SHOULD itself be observable. Implementations SHOULD log: PDU counts and types, Error rates, Authentication failures, Latency metrics, and Agent registration and trust transitions. This metadata MAY be exported to OpenTelemetry or similar observability systems. 14.4. Error Handling in Practice * Transient errors (rate_limited, back_pressure): Retry with backoff. * Authentication errors (auth_failed): Alert operator; do not retry with same credentials. * Protocol errors (malformed_pdu, unknown_type, schema_mismatch): Log for debugging; likely indicates implementation bug. * Policy errors (policy_denied, exec_disabled, config_disabled): Log; do not retry without policy change. * State errors (replay_detected): Log; may indicate misconfiguration or attack. 15. IANA Considerations This document requests the creation of a SAMP registry group under the "IANA Considerations" framework of [RFC8126]. Efstathiou Expires 18 February 2027 [Page 39] Internet-Draft SAMP August 2026 15.1. SAMP PDU Types Registry Registry Name: SAMP PDU Types Registration Policy: Specification Required Expert Review Guidelines: The designated expert SHOULD verify that new PDU types include a clear name, description, payload schema, direction semantics, error handling, and security considerations. Initial assignments: +==============+=================================+===============+ | Value | Description | Reference | +==============+=================================+===============+ | ping | Agent heartbeat | This document | +--------------+---------------------------------+---------------+ | discover | Agent self-announcement | This document | +--------------+---------------------------------+---------------+ | discover_ack | Manager response to DISCOVER | This document | +--------------+---------------------------------+---------------+ | query | State query | This document | +--------------+---------------------------------+---------------+ | push | Asynchronous event notification | This document | +--------------+---------------------------------+---------------+ | subscribe | Event subscription | This document | +--------------+---------------------------------+---------------+ | unsubscribe | Cancel subscription | This document | +--------------+---------------------------------+---------------+ | config | Configuration change | This document | +--------------+---------------------------------+---------------+ | exec | Execute operation | This document | +--------------+---------------------------------+---------------+ Table 12: Initial SAMP PDU Type Assignments 15.2. SAMP Error Codes Registry Registry Name: SAMP Error Codes Registration Policy: Specification Required Expert Review Guidelines: The designated expert SHOULD verify that new error codes include a clear name, description, and handling guidance. Initial assignments: Efstathiou Expires 18 February 2027 [Page 40] Internet-Draft SAMP August 2026 +=====================+=========================+===========+ | Value | Description | Reference | +=====================+=========================+===========+ | malformed_pdu | Invalid JSON or missing | This | | | required fields | document | +---------------------+-------------------------+-----------+ | unknown_type | Unrecognized PDU type | This | | | | document | +---------------------+-------------------------+-----------+ | invalid_value | Invalid field value | This | | | | document | +---------------------+-------------------------+-----------+ | schema_mismatch | Payload schema | This | | | validation failure | document | +---------------------+-------------------------+-----------+ | version_unsupported | Unsupported protocol | This | | | version | document | +---------------------+-------------------------+-----------+ | profile_invalid | Invalid or incomplete | This | | | profile | document | +---------------------+-------------------------+-----------+ | auth_failed | Authentication failure | This | | | | document | +---------------------+-------------------------+-----------+ | replay_detected | Replay attack detected | This | | | | document | +---------------------+-------------------------+-----------+ | unknown_field | Unknown field requested | This | | | | document | +---------------------+-------------------------+-----------+ | exec_disabled | EXEC not enabled | This | | | | document | +---------------------+-------------------------+-----------+ | config_disabled | CONFIG not enabled | This | | | | document | +---------------------+-------------------------+-----------+ | policy_denied | Manager policy denies | This | | | operation | document | +---------------------+-------------------------+-----------+ | rate_limited | Rate limiting in effect | This | | | | document | +---------------------+-------------------------+-----------+ | back_pressure | Receiver overloaded | This | | | | document | +---------------------+-------------------------+-----------+ | bootstrap_failed | Enrollment/bootstrap | This | | | failure | document | +---------------------+-------------------------+-----------+ Efstathiou Expires 18 February 2027 [Page 41] Internet-Draft SAMP August 2026 | internal_error | Internal receiver error | This | | | | document | +---------------------+-------------------------+-----------+ Table 13: Initial SAMP Error Code Assignments 15.3. SAMP Autonomy Classes Registry Registry Name: SAMP Autonomy Classes Registration Policy: Specification Required +======================+=============================+===========+ | Value | Description | Reference | +======================+=============================+===========+ | advisory | Read-only observation only | This | | | | document | +----------------------+-----------------------------+-----------+ | operational-readonly | Observation and self- | This | | | configuration | document | +----------------------+-----------------------------+-----------+ | operational-write | Configuration allowed, | This | | | limited execution | document | +----------------------+-----------------------------+-----------+ | critical-write | Configuration and execution | This | | | under strict policy | document | +----------------------+-----------------------------+-----------+ Table 14: Initial SAMP Autonomy Class Assignments 15.4. SAMP Trust States Registry Registry Name: SAMP Trust States Registration Policy: Specification Required Efstathiou Expires 18 February 2027 [Page 42] Internet-Draft SAMP August 2026 +=============+====================================+===============+ | Value | Description | Reference | +=============+====================================+===============+ | discovered | Agent announced, not yet evaluated | This document | +-------------+------------------------------------+---------------+ | pending | Manager awaiting trust decision | This document | +-------------+------------------------------------+---------------+ | trusted | Manager accepted agent | This document | +-------------+------------------------------------+---------------+ | quarantined | Isolated for observation | This document | +-------------+------------------------------------+---------------+ | rejected | Manager refused agent | This document | +-------------+------------------------------------+---------------+ | offline | Agent unreachable | This document | +-------------+------------------------------------+---------------+ | stale | Agent missed heartbeats beyond | This document | | | threshold | | +-------------+------------------------------------+---------------+ | revoked | Trust explicitly revoked | This document | +-------------+------------------------------------+---------------+ Table 15: Initial SAMP Trust State Assignments 15.5. SAMP Profile Namespaces Registry Registry Name: SAMP Profile Namespaces Registration Policy: Specification Required No initial assignments are made. The system category is defined in this document but is not a registry entry; it is a required profile category. Future profile namespaces (e.g., model, tools, memory) MAY be registered as implementations define them. 15.6. Media Type Registration This document does NOT request a media type registration. SAMP PDUs use application/json [RFC8259] as the content type. A dedicated SAMP media type (e.g., application/samp+json) MAY be requested in a future version if warranted. 16. Implementation Status This section records implementation status for early review and will be removed before publication as an RFC. At the time of writing, the following implementations exist: Efstathiou Expires 18 February 2027 [Page 43] Internet-Draft SAMP August 2026 * *Rust SAMP Core and SAMP Module*: Part of the AgMS reference implementation. Provides PDU encoding/decoding, profile management, authentication scaffolding, and an embeddable agent- side module. * *Python PoC*: A SAMP Collector (AgMS-lite) and an OpenClaw SAMP Adapter demonstrating DISCOVER, DISCOVER_ACK, PING, PING_ACK, QUERY, PUSH, and disabled-by-default EXEC flows over HTTP. 20 tests passing. The Python PoC signs raw request body bytes rather than canonical JSON. This is a known deviation from the specification in this document. The PoC SHOULD be updated to use RFC 8785 canonicalization for interoperability. SUBSCRIBE and UNSUBSCRIBE are defined in this specification but are not implemented in either the Rust or Python PoC as of the time of writing. 17. References 17.1. Normative References [RFC2104] Krawczyk, H., Bellare, M., and R. Canetti, "HMAC: Keyed- Hashing for Message Authentication", RFC 2104, February 1997, . [RFC2119] Bradner, S., "Key words for use in RFCs to Indicate Requirement Levels", BCP 14, RFC 2119, March 1997, . [RFC3339] Klyne, G. and C. Newman, "Date and Time on the Internet: Timestamps", RFC 3339, July 2002, . [RFC6234] Eastlake, D. and T. Hansen, "US Secure Hash Algorithms (SHA and SHA-based HMAC and HKDF)", RFC 6234, September 2011, . [RFC6455] Fette, I. and A. Melnikov, "The WebSocket Protocol", RFC 6455, December 2011, . [RFC8174] Leiba, B., "Ambiguity of Uppercase vs Lowercase in RFC 2119 Key Words", BCP 14, RFC 8174, May 2017, . Efstathiou Expires 18 February 2027 [Page 44] Internet-Draft SAMP August 2026 [RFC8259] Bray, T., "The JavaScript Object Notation (JSON) Data Interchange Format", STD 90, RFC 8259, December 2017, . [RFC8446] Rescorla, E., "The Transport Layer Security (TLS) Protocol Version 1.3", RFC 8446, August 2018, . [RFC8785] Rundgren, A. and B. Jordan, "JSON Canonicalization Scheme (JCS)", RFC 8785, June 2020, . [RFC9110] Fielding, R., Nottingham, M., and J. Reschke, "HTTP Semantics", STD 97, RFC 9110, June 2022, . [RFC9562] Davis, K., "Universally Unique IDentifiers (UUIDs)", RFC 9562, May 2024, . 17.2. Informative References [RFC3411] Harrington, D., "An Architecture for Describing Simple Network Management Protocol (SNMP) Management Frameworks", 2002, . [RFC3416] Presuhn, R., "Version 2 of the Protocol Operations for the Simple Network Management Protocol (SNMP)", 2002, . [RFC2578] McCloghrie, K., "Structure of Management Information Version 2 (SMIv2)", 1999, . [RFC2579] McCloghrie, K., "Textual Conventions for SMIv2", 1999, . [RFC2580] McCloghrie, K., "Conformance Statements for SMIv2", 1999, . [RFC6241] Enns, R., "Network Configuration Protocol (NETCONF)", 2011, . [RFC7950] Bjorklund, M., "The YANG 1.1 Data Modeling Language", 2016, . Efstathiou Expires 18 February 2027 [Page 45] Internet-Draft SAMP August 2026 [RFC8126] Cotton, M., "Guidelines for Writing an IANA Considerations Section in RFCs", 2017, . [OPAMP] OpenTelemetry SIG, "Open Agent Management Protocol (OpAMP)", . [MCP] Anthropic, "Model Context Protocol", . [A2A] Linux Foundation, "Agent-to-Agent Protocol", . Appendix A. Open Issues This initial draft leaves the following questions open: 1. *Profile schema format*: TOML is the authoring format for v0.1. Should the machine-readable validation schema use JSON Schema, CUE, YANG mapping, or another formalism? This remains open/ deferred for v0.1. 2. *Subscription persistence*: Should subscriptions survive agent reconnect in v0.1? Currently, they do not. This is deferred but may be revisited. 3. *Multi-manager conflict resolution*: Last-write-wins vs. policy- based vs. ownership-based. Deferred to future work. 4. *Media type*: Should SAMP register a dedicated media type (e.g., application/samp+json) instead of using application/json? The following items are definitively deferred for v0.1: * *EXEC confirmation tokens*: Deferred for a later version. SAMP v0.1 relies on profile policy, require_ack, cooldown, max_per_minute, and audit fields for EXEC safety. * *Endpoint path standardization*: The endpoint path is advertised by the agent in the DISCOVER payload and configured at the manager during bootstrap. /samp is a recommended convention. No mandatory path is defined for v0.1. * *Unicode normalization*: SAMP does not apply Unicode normalization during signing or verification. JSON strings are preserved exactly as they appear. See Section 9.4 for details. Efstathiou Expires 18 February 2027 [Page 46] Internet-Draft SAMP August 2026 Appendix B. Example SAMP Profile (TOML) agent_id = "selefkos-jr" name = "Selefkos Junior" agent_version = "2026.5.20" profile_version = "0.1" agent_type = "openclaw" autonomy_class = "operational-readonly" [system] status = "operational" uptime = 86400 version = "2026.5.20" last_seen = "2026-08-14T09:00:00Z" [model] primary = "glm-5.2" fallback = "kimi-k2.6" [exec_policy] enabled = false allowed_commands = [] dangerous_commands = [] require_ack = true cooldown = 60 max_per_minute = 5 scope = "agent" audit = true Appendix C. Example PDU Flows C.1. Discovery Flow Agent Manager | | |--- DISCOVER (request) ------->| | {profile, endpoint, | | capabilities} | | | |<-- DISCOVER_ACK (response) ---| | {state: "trusted", | | manager_version: "0.1"} | | | C.2. Query Flow Efstathiou Expires 18 February 2027 [Page 47] Internet-Draft SAMP August 2026 Manager Agent | | |--- QUERY (request) ---------->| | {fields: [ | | "system.status", | | "system.uptime"]} | | | |<-- QUERY (response) ---------| | {values: { | | "system.status": "ok", | | "system.uptime": 3600}, | | unknown: []} | | | C.3. Event Subscription Flow Manager Agent | | |--- SUBSCRIBE (request) ------>| | {event_types: ["alert"], | | category: "system", | | ttl_seconds: 300} | | | |<-- SUBSCRIBE (response) ------| | {subscription_id: "sub-1", | | ttl_seconds: 300} | | | |<-- PUSH (notification) -------| | {event: "alert", | | subscription_id: "sub-1", | | data: {...}} | | | |--- UNSUBSCRIBE (request) ---->| | {subscription_id: "sub-1"} | | | |<-- UNSUBSCRIBE (response) ----| | {cancelled: true} | | | Appendix D. Glossary +=============+=====================================+ | Term | Definition | +=============+=====================================+ | SAMP | Simple Agent Management Protocol | +-------------+-------------------------------------+ | PDU | Protocol Data Unit | +-------------+-------------------------------------+ Efstathiou Expires 18 February 2027 [Page 48] Internet-Draft SAMP August 2026 | Manager | System that manages agents via SAMP | +-------------+-------------------------------------+ | Agent | AI agent exposing a SAMP interface | +-------------+-------------------------------------+ | Profile | Structured declaration of agent | | | identity and capabilities | +-------------+-------------------------------------+ | Trust State | Manager-assigned state for an agent | +-------------+-------------------------------------+ | Autonomy | Advisory risk classification for an | | Class | agent | +-------------+-------------------------------------+ | Enrollment | Process of evaluating and accepting | | | an agent | +-------------+-------------------------------------+ | Conformance | Level of protocol support claimed | | Tier | by an implementation | +-------------+-------------------------------------+ Table 16: Glossary Author's Address Stelios E. Efstathiou Independent Email: ietf@samp-protocol.org Efstathiou Expires 18 February 2027 [Page 49]