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.
• Eight 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. The SNMP architecture and protocol operations are specified in and . SNMP is device-centric and uses MIB objects defined through SMIv2 structure, textual conventions, and conformance statements as specified in , , and . 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.

Runtime verification

Runtime-verification systems evaluate actions or state transitions and produce evidence. SAMP may transport or consume such evidence for management-policy and trust decisions, but it does not define verifier policy logic or require a specific evidence format.

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 .

SAMP Endpoint

The protocol endpoint implementing the SAMP Agent role. It may be embedded in the managed agent, implemented by a supervisor or sidecar, placed in an AI Agent Gateway, or provided by another infrastructure-control component.

Evidence Issuer

The entity that evaluates an evidence subject and produces a verdict or other runtime evidence. The issuer is distinct from a SAMP endpoint that merely sends or relays the evidence.

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

Endpoint Deployment Models and Failure Domains The SAMP Agent is a logical protocol role and does not imply a particular deployment topology. A SAMP endpoint may be embedded in the managed-agent process, implemented by a sidecar or supervisor, placed in an AI Agent Gateway, or implemented by another independent infrastructure-control component. These deployment models do not provide equivalent guarantees. An embedded endpoint may be suitable for cooperative management but can become unavailable or untrustworthy when the managed process fails or is compromised. An endpoint outside the managed agent's failure domain can provide stronger evidence delivery, isolation, quarantine, restart, and termination guarantees. A profile SHOULD declare the endpoint deployment model, whether the endpoint shares the managed agent's process, host, or failure domain, whether its management and evidence paths survive managed-process failure, and whether each advertised control operation is cooperative or independently enforceable. A manager MUST NOT infer out-of-band enforcement merely from the existence of a SAMP endpoint. Gateway deployment is a first-class SAMP deployment model and is RECOMMENDED for security-sensitive or higher-autonomy environments. The core protocol remains deployment-topology-neutral.

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

The internal structure of object and array values is opaque to the SAMP v0.1 core protocol unless a profile or field declaration supplies a schema identifier. A receiver MUST NOT infer a nested validation contract from the base type alone.

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. Implementations MUST enforce a configurable maximum profile size and SHOULD document the configured limit. A receiver MAY reject an oversized inline profile with a profile_invalid error.

Capabilities and Enablement A profile may advertise the protocol operations and optional features that an endpoint supports. Capability advertisement states implementation support only. It does not grant authority or enable CONFIG or EXEC. DISCOVER SHOULD identify the protocol versions supported by the sender. The profile_version field identifies the profile representation and is distinct from the protocol version. A manager selects only a mutually supported protocol version and MUST reject an unsupported version with version_unsupported.

Configuration Policy An endpoint advertising CONFIG MUST include a config_policy declaration. The declaration contains:

enabled

A boolean indicating whether CONFIG is locally enabled.

writable_fields

An array containing the dotted-path fields that may be changed. Fields not present in this allow-list are not writable.

field_schemas

An optional object mapping writable field names to schema identifiers or references approved by the deployment.

cooldown

An optional non-negative minimum interval, in seconds, between accepted CONFIG operations.

max_per_minute

An optional positive rate limit.

audit

A boolean indicating whether accepted and rejected CONFIG attempts are recorded locally.

The agent's local config_policy and the manager's policy are both restrictive: an operation is permitted only when both allow it. The declaration does not prove that a particular configuration change is behaviourally safe.

Execution Policy An endpoint advertising EXEC MUST include an exec_policy declaration. The declaration contains at least enabled, allowed_commands, per-command typed parameter schemas, and audit fields. It MAY also contain cooldown and max_per_minute limits. The agent's local exec_policy and the manager's policy are both restrictive. Static command and parameter declarations do not prove that a particular invocation is behaviourally safe. A deployment MAY require synchronous runtime evidence or an external verification decision for selected operations.

Deployment Metadata A profile MAY include a deployment object with the following fields:

endpoint_model

One of embedded, sidecar, supervisor, gateway, or infrastructure.

shared_process

Whether the SAMP endpoint shares the managed agent's process.

shared_host

Whether the SAMP endpoint shares the managed agent's host.

shared_failure_domain

Whether failure or compromise of the managed agent is expected to affect the endpoint.

management_path_survives_failure

Whether the management path is expected to remain available after managed-process failure.

evidence_path_survives_failure

Whether the evidence path is expected to remain available after managed-process failure.

independently_enforceable_operations

An array of operations enforceable without cooperation from the managed agent.

These fields are declarations and MUST NOT be treated as proof of independence. A manager SHOULD validate them against deployment inventory, attestation, or other trusted configuration when stronger guarantees are required.

Agent Relationships A profile MAY include parent_agent_id and relationship_type metadata. A related or subordinate agent enrolls independently and MUST NOT inherit trust or management authority solely from the declared relationship.

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 PDU with direction: "response".

DISCOVER

Agent-to-manager self-announcement and profile advertisement. The manager responds with a DISCOVER PDU with direction: "response".

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	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. QUERY, PUSH, SUBSCRIBE, UNSUBSCRIBE, CONFIG, and EXEC require an enrolled and authenticated peer. A manager MAY accept an unauthenticated DISCOVER only for bootstrap, in which case it MUST NOT create more than a discovered or pending registry entry. See for details.

Liveness Semantics A successful PING exchange establishes only that the peer's SAMP endpoint is reachable and responsive at that time. It does not establish workload progress, behavioural correctness, successful scheduling, task completion, or continued trustworthiness. Workload-specific progress is outside the SAMP v0.1 core protocol.

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 {}.
auth_tag	string	Conditional	HMAC-SHA256 authentication tag (see ). Required when authentication is enabled.
key_id	string	Optional	Opaque identifier for the configured shared secret. It is not an identity credential by itself.
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. The request sender generates request_id. It MUST be unique within that sender's authenticated identity for at least the replay-cache retention window. A notification uses its request_id as the identifier of that transmitted PDU; an event payload may additionally carry event_id and correlation_id with event-specific semantics.

Timestamp Validation Receivers SHOULD validate that timestamps are within an acceptable clock-skew window. The RECOMMENDED default is plus or minus 300 seconds and SHOULD be configurable. 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, self-reported endpoint status (e.g., "operational", "degraded"). It does not report workload progress or behavioural correctness.

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 payload (type: "discover", direction: "response"): 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 assigned_id is present, the agent MUST use that value as agent_id in subsequent PDUs for this enrollment. The manager MUST bind the assigned identifier to the authenticated enrollment context and MUST NOT allow the reassignment to overwrite another enrolled identity. 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. The optional severity field is distinct from category and describes operational importance. The event_id field uniquely identifies the event. An optional correlation_id associates the event with an action, request, or state transition. PUSH PDUs use direction: "notification". No response is expected unless the manager explicitly requests acknowledgment.

Runtime Evidence A PUSH event with event value "runtime_evidence" carries format-neutral evidence about an action, invocation, or state transition. Runtime evidence may also appear synchronously in a CONFIG or EXEC response when it gates the corresponding operation. The runtime-evidence object contains:

evidence_subject

An object identifying the action, invocation, or state transition evaluated.

issuer

The identity of the entity that evaluated the subject and produced the evidence.

sender

The identity of the SAMP endpoint sending or relaying the evidence, when different from the issuer.

phase

One of pre_admission, post_execution, or state_observation.

policy_outcome

One of allow, deny, or indeterminate.

processing_status

One of verified, unverifiable, malformed, or unsupported.

evidence_format

A format or profile identifier. The base protocol does not select a preferred format.

correlation

An object binding the evidence to the relevant request, action digest, target agent, operation type, and policy-profile version as applicable.

freshness

An object containing issued_at, expires_at, nonce, and an optional challenge_ref. A synchronous pre-admission profile SHOULD require challenge_ref.

evidence

Either an inline evidence object or a reference with an integrity digest and manager-approved retrieval metadata.

verifier_deployment

An object describing whether the issuer is in-process, on the same host, in the same failure domain, or independent.

recommended_action

An optional advisory management action such as observe, quarantine, or revoke.

The evidence issuer and SAMP sender are distinct roles. Transport authentication of the sender does not prove that the sender issued the verdict. Evidence-format profiles define issuer authentication and evidence validation. An allow outcome with a processing_status other than verified MUST be treated as indeterminate. A manager MUST reject evidence whose correlation or freshness requirements do not match the relying context, regardless of evidence-format signature validity. Pre-admission evidence that gates CONFIG or EXEC MUST be bound synchronously to that exchange. PUSH is suitable for post-execution evidence and independently generated notifications. On disagreement, the synchronous admission result controls the operation; subsequent evidence may inform a manager-controlled trust transition. A manager MAY use validated runtime evidence as input to trust transitions. Evidence and recommended_action do not directly change trust state. Manager policy remains authoritative. The absence of expected evidence MUST NOT be interpreted as evidence of correct behaviour. CCS receipts are one possible evidence-format binding. SAMP v0.1 neither requires CCS nor selects it as a preferred binding.

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. SAMP v0.1 defines only agent-wide scope. A session-scoped configuration requires a separately specified, transport-independent session model and is outside this document. 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. A response MAY include runtime_evidence as defined in . If manager policy requires pre-admission evidence, the agent MUST NOT apply the configuration before the required evidence has been synchronously validated.

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. A response MAY include runtime_evidence as defined in . If manager policy requires pre-admission evidence, the operation MUST NOT execute before the required evidence has been synchronously validated.

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

When authentication is enabled, unknown fields remain covered by the PDU authentication tag even when their semantics are ignored. A future extension that requires rejection when unsupported must define an explicit critical-extension mechanism; none is defined in SAMP v0.1.

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 authentication tag is placed in the auth_tag envelope field as a lowercase hex-encoded string.
4. The receiver recomputes the HMAC over the canonical form (excluding only the auth_tag field) and compares it to the received authentication tag.
5. If the authentication tag is missing or does not match, the receiver returns an auth_failed error.

Key Identification SAMP v0.1 uses a shared secret per manager-agent pair. A deployment MAY assign an opaque key_id so that a receiver can select among locally configured secrets during manual rotation. A receiver MUST NOT silently fall back to an unrelated key when an unknown key_id is received. Automated key rotation and negotiation are not defined in v0.1. 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 authentication tags.

Canonicalization Procedure

1. Take the PDU as a JSON object.
2. Remove only the auth_tag field from the object. All other envelope, payload, and extension fields, including timestamp, request_id, and key_id, remain covered.
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.

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

Verification Procedure

1. Perform inexpensive envelope-size, JSON-syntax, required-field, and timestamp checks.
2. Extract the auth_tag field from the received PDU.
3. Remove only the auth_tag field from the PDU object.
4. Apply RFC 8785 canonicalization to the modified object.
5. Encode as UTF-8.
6. Compute HMAC-SHA256 using the shared secret.
7. Compare the computed digest with the received authentication tag using a constant-time comparison.
8. If they match, authentication succeeds. If not, return auth_failed.
9. After authentication succeeds, consult replay state scoped to the authenticated sender identity.

Failure Behavior

• Missing auth_tag field when authentication is enabled: auth_failed error.
• Invalid authentication tag: auth_failed error.
• Malformed authentication tag (not a valid hex string): auth_failed error.

Unicode Normalization SAMP does not apply Unicode normalization during authentication-tag generation 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 authentication tag. Different Unicode code-point sequences produce different canonical bytes and therefore different HMAC authentication tags. 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 an authentication 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. Authentication requirements are unchanged by the WebSocket upgrade. If a connection carrying an active subscription is lost, the manager MUST re-establish the connection and re-subscribe unless both peers explicitly implement a persistence extension. Core v0.1 does not require event buffering or subscription persistence across reconnect.

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 auth_tag field removed. This is the same canonicalization used for HMAC authentication (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, QUERY, and PUSH request, response, and notification semantics as applicable. 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 authentication tags).
• 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 authentication tags.
• 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:

• After successful authentication, request_id and request digest are checked against replay state scoped to the authenticated sender. The request digest is SHA-256 over the RFC 8785 canonical bytes of the PDU with the auth_tag field removed. Same request_id with same digest returns a cached response when one exists; 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 defines enabled, allowed_commands, typed parameter schemas, and audit fields, and MAY define cooldown and max_per_minute limits.
• Manager policy MAY require synchronously bound runtime evidence before admitting a sensitive CONFIG or EXEC operation.

Failure-Domain and Evidence-Path Confusion An operator could assume that a SAMP endpoint can enforce control independently when it actually shares the managed agent's process or failure domain. A compromised or failed agent could also suppress evidence when the evidence path depends on that same domain. Mitigations in v0.1:

• Deployment metadata distinguishes embedded, supervised, gateway, and independent endpoint models.
• Managers MUST NOT infer independent enforcement from endpoint reachability alone.
• Evidence identifies issuer, sender, and verifier deployment separately.
• The absence of expected evidence MUST NOT be interpreted as evidence of correct behaviour.

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
Failure-domain confusion	Deployment declarations, separated issuer and sender roles	Attestation and independently validated topology inventory

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. Runtime evidence may reveal action digests, policy decisions, verifier identities, or references to protected evidence stores. Evidence references MUST NOT embed reusable credentials. Managers MUST apply authorization and data-minimization policy before retrieving, storing, or exporting evidence.

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
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, PING, QUERY, PUSH, and disabled-by-default EXEC flows over HTTP. Request and response roles use the direction field. 20 tests passing.

The Python PoC authenticates raw request body bytes rather than RFC 8785 canonical JSON. This is a known deviation from the specification in this document. The PoC SHOULD be updated 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

Changes from -00

• Clarified topology-neutral endpoint deployment models, failure-domain relationships, and independently enforceable operations.
• Distinguished endpoint liveness from workload progress, behavioural correctness, and trust.
• Added a format-neutral runtime-evidence interface for PUSH and synchronous CONFIG/EXEC binding without selecting a preferred evidence format.
• Defined config_policy and writable_fields, and clarified exec_policy.
• Unified request and response operation types through the direction field and removed separate ACK-type nomenclature.
• Clarified request-ID scope, configurable clock skew, HMAC coverage, key identification, and authenticated replay processing.
• Replaced digital-signature terminology for HMAC with authentication-tag terminology.
• Clarified capability advertisement, identifier assignment, WebSocket reconnect behaviour, privacy boundaries, and example flows.

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, typed command schemas, optional runtime evidence, 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 authentication-tag generation or verification. JSON strings are preserved exactly as they appear. See for details.

Example SAMP Profile (JSON Wire Representation)

Example SAMP Profile (TOML)

Example PDU Flows

Discovery Flow | | {profile, endpoint, | | capabilities} | | | |<-- DISCOVER (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} | | | ]]>

Configuration Flow | | {fields: { | | "system.log_level": | | "debug"}} | | | |<-- CONFIG (response) --------| | {applied: [ | | "system.log_level"], | | rejected: []} | ]]>

Execution Rejection Flow | | {command: "session_reset",| | params: {session_id: | | "sess-001"}} | | | |<-- EXEC (error) -------------| | {code: "exec_disabled", | | message: "EXEC is not | | enabled"} | ]]>

Runtime-Evidence Notification Flow | | {event: | | "runtime_evidence", | | event_id: "...", | | data: { | | issuer: "...", | | phase: "post_execution",| | policy_outcome: "deny", | | processing_status: | | "verified", | | evidence_format: "...", | | correlation: {...}, | | freshness: {...}, | | evidence: {...}}} | ]]>

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