Simple Agent Management Protocol (SAMP)

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

1.2. Relationship to Existing Protocols

SAMP occupies the AI agent management plane. It is intended to coexist with existing management, telemetry, tool, and agent-communication protocols.¶

SNMP

SAMP is SNMP-inspired, but not SNMP-compatible. The SNMP architecture and protocol operations are specified in [RFC3411] and [RFC3416]. SNMP is device-centric and uses MIB objects defined through SMIv2 structure, textual conventions, and conformance statements as specified in [RFC2578], [RFC2579], and [RFC2580]. SAMP adds AI-agent concepts such as dynamic profiles, autonomy classes, enrollment, trust states, and policy-gated execution.¶

NETCONF/YANG

NETCONF [RFC6241] and YANG [RFC7950] provide strong configuration and modeling facilities for network devices. SAMP targets agent lifecycle, discovery, trust, and runtime management. A future SAMP profile model could be mapped to YANG, but that is outside this document.¶

OpenTelemetry

OpenTelemetry provides observability for traces, metrics, and logs. SAMP can export or correlate events with observability systems, but it defines management operations that observability systems do not provide.¶

OpenTelemetry OpAMP

The Open Agent Management Protocol (OpAMP) [OPAMP] manages telemetry and data-collection agents. SAMP addresses autonomous and semi-autonomous AI agents as operational entities. The two protocols are complementary and can coexist in the same management architecture. A deployment may use OpAMP for its telemetry collectors and SAMP for its AI agents, with a unified management dashboard.¶

MCP

MCP [MCP] is a tool-use interface for applications and agents. SAMP is a management interface for operators and management systems.¶

A2A and ACP

Agent-to-agent protocols [A2A] define peer communication and collaboration. SAMP defines manager-to-agent management.¶

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

7.1. PDU Directions

Each PDU has a direction field indicating its role:¶

7.2. PDU Exchange Patterns

7.3. Authentication Requirements by PDU

All PDUs exchanged between a manager and an agent MUST be authenticated when authentication is enabled. 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 Section 9 for details.¶

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

7.5. DISCOVER Rate Limiting

Managers SHOULD rate-limit DISCOVER messages from unknown agents to prevent discovery flooding. A manager MAY maintain a pending-agent quota and reject excess discoveries with a rate_limited error.¶

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

8.1. Common PDU Envelope

The following table defines the envelope fields:¶

8.2. PDU-Specific Payloads

{}

{"status": "operational"}

{
  "profile": {},
  "endpoint": "https://agent.example/samp",
  "capabilities": ["query", "push", "exec"]
}

{
  "state": "trusted",
  "manager_version": "0.1",
  "assigned_id": "agent-001"
}

{
  "state": "rejected",
  "reason": "profile_invalid"
}

{
  "fields": ["system.status", "system.uptime", "model.primary"]
}

{
  "values": {
    "system.status": "operational",
    "system.uptime": 86400
  },
  "unknown": ["model.primary"]
}

{
  "event": "status_change",
  "data": {
    "old_status": "operational",
    "new_status": "degraded"
  },
  "category": "system",
  "severity": "warning",
  "event_id": "d9df237c-f7cd-4fc8-b4e7-d35c676ad20f"
}

{
  "event_types": ["status_change", "alert"],
  "category": "system",
  "ttl_seconds": 300
}

{
  "subscription_id": "sub-abc123",
  "ttl_seconds": 300,
  "renew_before": "2026-08-14T09:05:00Z"
}

{"subscription_id": "sub-abc123"}

{"cancelled": true}

{
  "fields": {
    "model.fallback": "kimi-k2.6",
    "system.log_level": "debug"
  },
  "scope": "agent"
}

{
  "applied": ["model.fallback", "system.log_level"],
  "rejected": []
}

{
  "applied": ["system.log_level"],
  "rejected": [
    {"field": "model.fallback", "reason": "read_only"}
  ]
}

{
  "command": "session_reset",
  "params": {
    "session_id": "sess-001"
  }
}

{
  "result": "success",
  "output": {
    "reset": true
  }
}

{
  "result": "exec_disabled",
  "detail": "EXEC is not enabled for this agent"
}

8.3. Error Envelope

When an error occurs, the response PDU has direction: "error" and the payload contains an error object:¶

{
  "version": "0.1",
  "type": "query",
  "direction": "error",
  "agent_id": "agent-001",
  "timestamp": "2026-08-14T09:00:01Z",
  "request_id": "24f8587c-4c4b-4e41-9f47-222c0f5f8b8b",
  "payload": {
    "error": {
      "code": "unknown_field",
      "detail": "Field 'model.primary' is not exposed",
      "timestamp": "2026-08-14T09:00:01Z"
    }
  }
}

The error payload object has the following fields:¶

8.5. JSON Encoding Requirements

• All SAMP JSON MUST be encoded as UTF-8 [RFC8259].¶
• Implementations MUST NOT include byte-order marks (BOM).¶
• Implementations MUST NOT use non-standard JSON extensions (e.g., trailing commas, comments).¶
• Field names in the envelope and in defined payloads are lowercase with underscores (e.g., request_id, agent_id).¶
• Timestamps MUST use RFC 3339 UTC format with the Z designator [RFC3339].¶
• UUIDs MUST be in canonical string form [RFC9562].¶
• Unknown envelope fields MUST be ignored (forward compatibility).¶
• Unknown PDU types MUST return unknown_type error.¶

8.6. Behavior for Unknown Fields and Unknown PDU Types

• Unknown envelope fields: MUST be ignored. This enables forward compatibility.¶
• Unknown PDU types: MUST return an unknown_type error.¶
• Unknown payload fields within a known PDU type: MUST be ignored, unless the PDU type explicitly defines strict validation.¶
• Unknown profile fields: MUST be ignored by the manager during validation, but SHOULD be logged.¶

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

9.1. 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 Section 9.4).¶
• Transport confidentiality: Provided by TLS 1.3 [RFC8446] for HTTPS. SAMP does not define its own transport encryption.¶
• Authorization policy: Enforced by the manager based on trust state, autonomy class, and local policy. Authentication is a prerequisite for authorization, not a substitute.¶

9.2. HMAC-SHA256 Signing

When authentication is enabled:¶

1. The sender computes a canonical JSON representation of the PDU (see Section 9.4).¶
2. The sender computes HMAC-SHA256 over the canonical bytes using the shared secret.¶
3. The resulting 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.¶

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

10.1. HTTP Transport

SAMP v0.1 requires HTTP [RFC9110] as the baseline transport.¶

10.2. WebSocket Transport

WebSocket support is OPTIONAL in SAMP v0.1. WebSocket is primarily useful for:¶

• Persistent event streams (subscription delivery).¶
• Frequent heartbeats (reducing HTTP overhead).¶
• Bidirectional communication without polling.¶

When WebSocket is used:¶

• The connection upgrade follows the WebSocket protocol [RFC6455].¶
• SAMP PDUs are sent as WebSocket text frames containing the JSON envelope.¶
• The same PDU envelope format and authentication rules apply.¶
• A WebSocket connection does not change the request-response semantics of individual PDUs.¶

WebSocket transport is NOT required for any conformance tier in v0.1.¶

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

10.3. Retry and Backoff

Implementations MAY retry failed requests with exponential backoff. Retries of the same request MUST use the same request_id as the original attempt. The receiver SHOULD cache the request digest and the corresponding response for a limited time period.¶

The request digest is SHA-256 over the RFC 8785 canonical bytes of the PDU with the auth_tag field removed. This is the same canonicalization used for HMAC authentication (see Section 9.4), with the addition of a SHA-256 hash over the canonical bytes.¶

• If the receiver sees the same request_id with the same request digest, it returns the cached response without re-executing the operation.¶
• If the receiver sees the same request_id with a different request digest, it rejects the PDU with a replay_detected error.¶

Non-idempotent operations, especially EXEC, SHOULD NOT be retried unless the receiver supports safe cached-response behavior for that operation type.¶

11.1. Mandatory Implementation Requirements

All tiers MUST support:¶

• JSON encoding [RFC8259].¶
• HTTP transport.¶
• Profile parsing and validation.¶
• HMAC-SHA256 authentication support (implementation MUST support it; deployment MAY disable it for localhost only).¶
• Standard error envelopes and error codes.¶
• PDU envelope parsing with all required fields.¶

11.2. Conformance Testing

Implementations claiming a conformance tier SHOULD be validated against a test suite covering:¶

• All required PDUs for the claimed tier.¶
• Profile validation.¶
• Authentication (enable/disable, valid/invalid 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.¶

12.1. Threat Model

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

12.2. Audit Requirements

Implementations SHOULD log all CONFIG and EXEC operations, including: Timestamp, Agent ID, Manager ID (if identifiable), Operation details (field changes, command, parameters), and Result (success/failure).¶

Audit logs SHOULD be tamper-evident and stored separately from the system being managed.¶

12.3. Rate Limiting and Back-Pressure

Managers and agents SHOULD implement rate limiting for incoming PDUs. Rate limiting MAY be applied per-agent, per-PDU-type, or globally. Excess requests SHOULD be rejected with rate_limited or back_pressure errors.¶

12.4. Trust Bootstrap

The initial trust establishment between a manager and an agent is a critical moment. SAMP v0.1 supports: Manual approval by the operator, Pre-shared enrollment tokens, and Public key thumbprint matching.¶

Future versions MAY support certificate-based enrollment and automated trust establishment.¶

12.5. Token Rotation and Storage

Shared secrets SHOULD be rotated periodically. Rotation frequency is a deployment decision. Tokens SHOULD be stored in a secrets manager (e.g., HashiCorp Vault, AWS Secrets Manager) rather than plaintext files.¶

Token rotation in v0.1 requires out-of-band coordination between the manager and agent. Automated rotation is future work.¶

12.6. Summary: Current Requirements vs Future Work

13.1. Sensitive Metadata Exposure

SAMP profiles and query responses can expose sensitive information about an agent, including: Framework details and version, Model names and provider information, Configuration values, Active sessions, Tool availability, Memory backends, Operational state, and Uptime and availability patterns.¶

Managers and agents SHOULD minimize exposed fields. Profiles SHOULD include only fields necessary for management. QUERY responses SHOULD NOT include secrets, credentials, prompt contents, private user data, or tool outputs unless explicitly required and authorized.¶

13.2. Event Data Sensitivity

PUSH events can contain operationally sensitive information, including: Status changes revealing operational patterns, Error details exposing internal architecture, Performance metrics revealing capacity or load, and Configuration changes revealing business logic.¶

Operators SHOULD classify and filter events before exporting them to telemetry, logging, or ticketing systems. Events containing user data MUST be handled according to applicable data protection regulations.¶

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

13.3. Data Minimization

Agents SHOULD expose the minimum profile data necessary for management. Managers SHOULD query only the fields they need. Bulk profile export or full-state queries SHOULD be restricted to authorized operators.¶

13.4. Log Protection

SAMP audit logs and event stores may contain sensitive operational data. Logs SHOULD be: Access-controlled, Retained according to a defined policy, Protected against tampering, and Sanitized before sharing or export.¶

14.1. Network Placement

SAMP deployments SHOULD place managers and agents on a dedicated management network or equivalent restricted trust boundary. Firewall rules SHOULD limit SAMP traffic to known managers and agents.¶

Agents SHOULD maintain an allow-list of authorized manager addresses. Managers SHOULD maintain an allow-list or pre-registration registry for expected agents.¶

14.2. Scaling

SAMP v0.1 targets single-agent interactions. A single manager MAY manage multiple agents, but fleet-scale bulk operations are not defined in v0.1. Deployments needing fleet-scale operations SHOULD use external orchestration (e.g., scripts, configuration management) layered on top of SAMP.¶

Scaling approaches compatible with v0.1:¶

• HTTP-only polling: Agents are polled by the manager at intervals. Suitable for moderate agent counts.¶
• Hierarchical managers: A tier of intermediate managers collects from agents and reports to a central manager. Requires out-of-band coordination.¶
• Queue-based ingestion: PUSH events are sent to a message queue rather than directly to the manager. Requires agent-side queue configuration.¶

Federation, multi-manager conflict resolution, and transactional configuration are future work.¶

14.3. Observability

SAMP management traffic SHOULD itself be observable. Implementations SHOULD log: PDU counts and types, Error rates, Authentication failures, Latency metrics, and Agent registration and trust transitions.¶

This metadata MAY be exported to OpenTelemetry or similar observability systems.¶

14.4. Error Handling in Practice

• Transient errors (rate_limited, back_pressure): Retry with backoff.¶
• Authentication errors (auth_failed): Alert operator; do not retry with same credentials.¶
• Protocol errors (malformed_pdu, unknown_type, schema_mismatch): Log for debugging; likely indicates implementation bug.¶
• Policy errors (policy_denied, exec_disabled, config_disabled): Log; do not retry without policy change.¶
• State errors (replay_detected): Log; may indicate misconfiguration or attack.¶

15.1. SAMP PDU Types Registry

Registry Name: SAMP PDU Types¶

Registration Policy: Specification Required¶

Expert Review Guidelines: The designated expert SHOULD verify that new PDU types include a clear name, description, payload schema, direction semantics, error handling, and security considerations.¶

Initial assignments:¶

15.2. SAMP Error Codes Registry

Registry Name: SAMP Error Codes¶

Registration Policy: Specification Required¶

Expert Review Guidelines: The designated expert SHOULD verify that new error codes include a clear name, description, and handling guidance.¶

Initial assignments:¶

15.3. SAMP Autonomy Classes Registry

Registry Name: SAMP Autonomy Classes¶

Registration Policy: Specification Required¶

15.4. SAMP Trust States Registry

Registry Name: SAMP Trust States¶

Registration Policy: Specification Required¶

15.5. SAMP Profile Namespaces Registry

Registry Name: SAMP Profile Namespaces¶

Registration Policy: Specification Required¶

No initial assignments are made. The system category is defined in this document but is not a registry entry; it is a required profile category. Future profile namespaces (e.g., model, tools, memory) MAY be registered as implementations define them.¶

15.6. Media Type Registration

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