Simple Agent Management Protocol (SAMP)

1.1. Scope

SAMP v0.1 defines:¶

• A JSON-based message format and common PDU envelope.¶
• Nine PDU types covering discovery, heartbeat, query, event notification, subscription, configuration, and execution.¶
• A profile model for agent identity, exposed fields, and policy declarations.¶
• Trust states and an enrollment model.¶
• Autonomy classes as advisory metadata for manager policy.¶
• HMAC-SHA256 message authentication.¶
• HTTP(S) as the baseline transport.¶
• Conformance tiers.¶
• IANA registry framework.¶

SAMP v0.1 does NOT define:¶

• Federation or multi-manager coordination.¶
• Fleet-wide bulk or transactional operations.¶
• Role-based access control (RBAC).¶
• Mandatory mutual TLS (mTLS).¶
• A formal profile schema language (e.g., JSON Schema, YANG).¶
• Agent-to-agent communication.¶
• Agent tool-use interfaces.¶
• Model selection or inference protocols.¶

1.2. Relationship to Existing Protocols

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

SNMP

SAMP is SNMP-inspired, but not SNMP-compatible. SNMP [RFC3411]/[RFC3416] is device-centric and based on MIB objects [RFC2578]/[RFC2579]/[RFC2580] and GET/SET/TRAP operations. SAMP adds AI-agent concepts such as dynamic profiles, autonomy classes, enrollment, trust states, and policy-gated execution.¶

NETCONF/YANG

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

OpenTelemetry

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

OpenTelemetry OpAMP

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

MCP

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

A2A and ACP

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

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. See Section 9 for details.¶

7.4. DISCOVER Rate Limiting

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

7.5. SUBSCRIBE and UNSUBSCRIBE Semantics

When a manager sends SUBSCRIBE, the agent allocates a subscription and returns a subscription_id in the response. Subsequent PUSH PDUs related to that subscription include the subscription_id in the envelope.¶

Subscriptions have a manager-defined or agent-defined time-to-live (TTL). A subscription that is not renewed within its TTL expires automatically. Managers SHOULD renew subscriptions before expiry.¶

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": { /* full SAMP Profile object */ },
  "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"
}

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

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

9.3. Key Identification

SAMP v0.1 uses a single shared secret per manager-agent pair. Key identification (e.g., key IDs) is not defined in v0.1. Future versions MAY introduce key identification for multi-key support.¶

Key distribution is out of band. Implementations SHOULD store shared secrets in a secrets manager, not in plaintext configuration files.¶

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

10.3. Retry and Backoff

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

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

• If the receiver sees the same request_id with the same request digest, it returns the cached response without re-executing the operation.¶
• 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 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.¶

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

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