Independent

ietf@samp-protocol.org

Operations and Management Individual Submission SAMP agent management AI agent management protocol 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.

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. 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.

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.

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 / is device-centric and based on MIB objects // 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 and YANG 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) 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 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 define peer communication and collaboration. SAMP defines manager-to-agent management.

Protocol Layer Comparison

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 management	OpAMP	Manage data-collection agents
AI agent management	SAMP	Manage autonomous/semi-autonomous AI agents

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 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, pending, trusted, quarantined, rejected, offline, stale, or revoked.

Conformance Tier

A defined level of protocol support that an implementation may claim. See .

Architecture The basic SAMP architecture contains a manager and one or more agents: | 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.

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.
• 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.

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.

Trust Transitions Trust transitions are controlled by the manager. Agents MUST NOT self-promote to trusted. The following transitions are normative:

• 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.

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.

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.

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.

Required Identity Fields The following fields MUST be present in every SAMP Profile: Required Profile Identity Fields

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 )

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: Profile Field Types

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

Minimal Required Category Every profile MUST include a system category with at least the following fields: Required System Category 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

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.
• Valid autonomy_class value (see ).
• 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.

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.

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.

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").

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.

PDU Directions Each PDU has a direction field indicating its role: PDU Directions

Direction	Meaning
request	Initiates an operation
response	Responds to a request
notification	Unsolicited asynchronous message
error	Error response to a request

PDU Exchange Patterns 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

Authentication Requirements by PDU All PDUs exchanged between a manager and an agent MUST be authenticated when authentication is enabled. See for details.

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.

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. 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.

Message Format All SAMP messages use a common PDU envelope encoded as UTF-8 JSON in SAMP version 0.1.

Common PDU Envelope The following table defines the envelope fields: Common PDU Envelope Fields

Field	Type	Presence	Description
version	string	Required	Protocol version, e.g., "0.1"
type	string	Required	PDU type (see )
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
request_id	string	Required	UUID for correlation and replay protection
payload	object	Required	PDU-specific JSON object. Empty payloads encode as {}.
signature	string	Conditional	HMAC-SHA256 signature (see ). Required when authentication is enabled.
sequence	int	Optional	Sequence number for ordered streams
subscription_id	string	Optional	Subscription identifier for SUBSCRIBE/UNSUBSCRIBE/PUSH

Field Validation Rules

• version MUST be "0.1" for this version of the protocol.
• type MUST be one of the PDU types listed in , 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 . 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.

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.

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.

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.

PDU-Specific Payloads

PING Request payload: Response payload: The status field in the response is a free-form string indicating the agent's self-reported status (e.g., "operational", "degraded").

DISCOVER Request payload: 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: 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:

QUERY Request payload: 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: 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.

PUSH Notification payload: 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.

SUBSCRIBE Request payload: 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:

UNSUBSCRIBE Request payload: Response payload:

CONFIG Request payload: 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: The applied array lists fields that were successfully changed. The rejected array lists fields that were rejected, with optional reasons: 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.

EXEC Request payload: 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: If the command is rejected, the response contains: 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.

Error Envelope When an error occurs, the response PDU has direction: "error" and the payload contains an error object: The error payload object has the following fields: Error Payload Fields

Field	Type	Presence	Description
code	string	Required	Error code (see )
detail	string	Optional	Human-readable error detail
timestamp	string	Required	UTC timestamp in RFC 3339 format

Error Codes The following error codes are defined for SAMP v0.1: SAMP Error Codes

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

JSON Encoding Requirements

• All SAMP JSON MUST be encoded as UTF-8 .
• 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 .
• UUIDs MUST be in canonical string form .
• Unknown envelope fields MUST be ignored (forward compatibility).
• Unknown PDU types MUST return unknown_type error.

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.

Authentication SAMP v0.1 uses shared-secret authentication with HMAC-SHA256 .

Authentication Model SAMP distinguishes between:

• Mandatory implementation support: All conformant SAMP v0.1 implementations MUST support HMAC-SHA256 message authentication.
• 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 ).
• Transport confidentiality: Provided by TLS 1.3 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.

HMAC-SHA256 Signing When authentication is enabled:

1. The sender computes a canonical JSON representation of the PDU (see ).
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.

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.

Canonical JSON SAMP v0.1 uses the JSON Canonicalization Scheme (JCS) defined in for computing HMAC signatures.

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.

Signature Representation The signature field contains the lowercase hex-encoded HMAC-SHA256 digest. Example signature value: a1b2c3d4e5f6... (64 hex characters).

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.

Failure Behavior

• 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.

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.

Transport Mapping SAMP defines protocol semantics and message envelopes independently from the underlying transport.

HTTP Transport SAMP v0.1 requires HTTP as the baseline transport.

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.

Content-Type The Content-Type header MUST be application/json.

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).

HTTP Status Codes SAMP uses HTTP status codes as follows: HTTP Status Code Mapping

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

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.

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.
• TLS 1.3 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.

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 .
• 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.

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 ), 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.
• 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.

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.

Mandatory Implementation Requirements All tiers MUST support:

• JSON encoding .
• 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.

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).
• 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.

Security Considerations

Threat Model SAMP v0.1 is designed for controlled environments. The following threats are identified:

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.

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.

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).

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.

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.
• Managers SHOULD cross-check advertised capabilities against pre-registration data.

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.

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.

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.

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.

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.

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.

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.

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.

Summary: Current Requirements vs Future Work Security Mitigations: v0.1 vs Future

Threat	v0.1 Mitigation	Future Enhancement
Rogue managers	Manager allow-list, HMAC	mTLS, per-agent keys
Rogue agents	Profile validation, enrollment	Signed profiles, cert identity
Credential theft	Secrets manager, rotation	Per-agent Ed25519 keys
Replay	request_id cache, timestamp	Persistent cache, sequence validation
Profile spoofing	Manager policy authoritative	Signed profiles
Unauthorized EXEC/CONFIG	Disabled by default, policy	RBAC, OPA integration
Version downgrade	Reject unsupported versions	Version negotiation
Flooding	Rate limiting, back-pressure	Flow-control protocol
Registry poisoning	Auth-required updates	Signed registrations

Privacy Considerations

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.

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.

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.

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.

Operational Considerations

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.

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:

• 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.

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.

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.

IANA Considerations This document requests the creation of a SAMP registry group under the "IANA Considerations" framework of .

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: Initial SAMP PDU Type 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

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: Initial SAMP Error Code Assignments

Value	Description	Reference
malformed_pdu	Invalid JSON or missing required fields	This document
unknown_type	Unrecognized PDU type	This document
invalid_value	Invalid field value	This document
schema_mismatch	Payload schema validation failure	This document
version_unsupported	Unsupported protocol version	This document
profile_invalid	Invalid or incomplete profile	This 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 operation	This document
rate_limited	Rate limiting in effect	This document
back_pressure	Receiver overloaded	This document
bootstrap_failed	Enrollment/bootstrap failure	This document
internal_error	Internal receiver error	This document

SAMP Autonomy Classes Registry Registry Name: SAMP Autonomy Classes Registration Policy: Specification Required Initial SAMP Autonomy Class Assignments

Value	Description	Reference
advisory	Read-only observation only	This document
operational-readonly	Observation and self-configuration	This document
operational-write	Configuration allowed, limited execution	This document
critical-write	Configuration and execution under strict policy	This document

SAMP Trust States Registry Registry Name: SAMP Trust States Registration Policy: Specification Required Initial SAMP Trust State Assignments

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 threshold	This document
revoked	Trust explicitly revoked	This document

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.

Media Type Registration This document does NOT request a media type registration. SAMP PDUs use application/json as the content type. A dedicated SAMP media type (e.g., application/samp+json) MAY be requested in a future version if warranted.

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:

• 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.

Normative References Informative References OpenTelemetry SIG Anthropic Linux Foundation

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 for details.

Example SAMP Profile (TOML)

Example PDU Flows

Discovery Flow | | {profile, endpoint, | | capabilities} | | | |<-- DISCOVER_ACK (response) ---| | {state: "trusted", | | manager_version: "0.1"} | | | ]]>

Query Flow | | {fields: [ | | "system.status", | | "system.uptime"]} | | | |<-- QUERY (response) ---------| | {values: { | | "system.status": "ok", | | "system.uptime": 3600}, | | unknown: []} | | | ]]>

Event Subscription Flow | | {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} | | | ]]>

Glossary Glossary

Term	Definition
SAMP	Simple Agent Management Protocol
PDU	Protocol Data Unit
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 Class	Advisory risk classification for an agent
Enrollment	Process of evaluating and accepting an agent
Conformance Tier	Level of protocol support claimed by an implementation