SAMP Engineering Notes #03

Inside the SAMP Management Plane

Imagine an organization operating fifty AI agents.

Some perform software development tasks. Others analyze security events, process documents, coordinate workflows, or interact with external systems.

They may use different frameworks, different models, different memory systems, and different execution environments.

Some run continuously. Others are started when needed.

A few may have permission to perform operations affecting critical infrastructure.

Now imagine the infrastructure team responsible for operating this environment.

How does the team know which agents exist, which are reachable, which are trusted, and which operations can safely be performed on them?

This is the problem addressed by the Simple Agent Management Protocol (SAMP).

In the previous article, we examined how established network-management principles inspired SAMP.

Now we will look inside the management plane itself.

Not simply at the protocol messages, but at how the components cooperate to establish a manageable operational environment.

1. Two Roles, One Management Relationship

At its core, SAMP defines two logical roles.

The SAMP Manager

The Manager is responsible for the management relationship with one or more AI agents.

Its responsibilities include:

• Maintaining a registry of known agents.
• Evaluating enrollment and trust.
• Observing endpoint reachability.
• Requesting operational information.
• Managing event subscriptions.
• Applying management policy.
• Initiating authorized configuration or execution requests.
• Recording relevant operational decisions and outcomes.

A Manager may be implemented as a standalone service or as part of a larger management application.

The SAMP Agent

The SAMP Agent is the logical management endpoint representing a managed AI agent.

It exposes the protocol interface through which management operations are performed.

Its responsibilities include:

• Announcing its identity and management profile.
• Sending heartbeat information.
• Exposing declared operational fields.
• Responding to supported management queries.
• Reporting events.
• Managing subscriptions.
• Validating configuration and execution requests.
• Enforcing applicable local restrictions.

The SAMP Agent does not necessarily perform the AI workload's reasoning or task execution itself.

It may be embedded within the agent's process or implemented through a separate management component.

The important architectural distinction is this:

The SAMP Manager manages the operational relationship. The SAMP Agent exposes the management interface. Neither role defines how the underlying AI system thinks.

2. A Practical Example: An Agent Joins the Environment

Consider a hypothetical security-analysis agent being introduced into an organization's infrastructure.

The agent is already capable of analyzing events and producing security findings.

However, being operational does not automatically make it a trusted member of the management environment.

SAMP provides a structured path for establishing that relationship.

Step 1: DISCOVER

The Agent sends a DISCOVER request to the Manager.

The request introduces the agent and its declared management profile.

Depending on the enrollment context, the Manager may evaluate the announced identity, endpoint information, profile, and relevant authentication material.

An initial unauthenticated discovery may be permitted for bootstrap, but it cannot establish trusted enrollment.

The Manager records the agent under the applicable initial trust conditions.

Discovery means the Manager has learned about an agent. It does not mean the agent has been trusted.

Step 2: Enrollment and Trust Evaluation

The Manager evaluates the agent according to deployment policy.

The process may involve provisioned credentials, profile validation, operational approval, or other external checks.

SAMP does not define the organization's entire enrollment workflow.

It defines the relevant management relationship and the protocol constraints that implementations must respect.

After the required validation, the Manager may authorize a transition to the trusted state.

But even then, trust does not automatically enable configuration or execution operations.

Step 3: PING

Once participating in the management environment, the Agent sends periodic PING requests.

This is an important architectural detail.

In SAMP, PING is initiated by the Agent toward the Manager.

A valid heartbeat exchange helps the Manager determine whether the SAMP endpoint is reachable.

It does not establish that the underlying AI workload is performing useful work.

An endpoint can remain responsive while the agent's task-processing subsystem is stalled.

That distinction matters.

Step 4: QUERY

The Manager can request declared operational information from the Agent.

For example, the Manager may query exposed system status, version information, or other supported management fields.

The Agent returns the requested values according to its profile declarations and applicable authorization requirements.

QUERY does not provide unrestricted access to the agent's memory, internal reasoning, or private implementation details.

Step 5: PUSH

Suppose the agent encounters an operational error.

It can send a PUSH notification to the Manager.

The notification may identify the event, severity, correlation information, and available operational context.

The Manager can use this information for monitoring, investigation, alerting, or other management workflows.

The event does not automatically authorize corrective action.

Step 6: Controlled Management

If operational intervention becomes necessary, the Manager may initiate a supported CONFIG or EXEC operation.

However, the requested operation must satisfy the applicable profile declarations, authorization requirements, and endpoint-local enforcement rules.

A trusted management relationship is necessary for many operations, but it is not a substitute for operation-specific authorization.

This gives us a complete conceptual management sequence:

Discover. Evaluate trust. Observe. Query. Receive events. Authorize. Act. Verify.

These are logical stages of a management workflow, not a mandatory sequence of nine protocol PDUs.

3. The Eight SAMP Protocol Operations

SAMP version 0.2 defines eight Protocol Data Unit (PDU) types.

Their directions are part of the protocol contract.

All operations except PUSH use request/response exchanges.

PUSH is an asynchronous notification and has no SAMP-level acknowledgment PDU.

This distinction has practical consequences.

A successful HTTP response to PUSH indicates transport-level completion, not proof that the receiving application durably stored or processed the event.

Likewise, a successful HTTP response to CONFIG or EXEC must not automatically be interpreted as proof that the intended external effect succeeded.

Transport success, protocol processing, and operational success are different things.

4. The Common Message Envelope

A management protocol needs more than operation names.

It must define how messages are identified, authenticated, correlated, and validated.

SAMP uses a common JSON-based PDU envelope.

The envelope carries information such as:

• Protocol version.
• PDU type.
• Message direction.
• Managed agent identifier.
• Timestamp.
• Request identifier.
• Operation-specific payload.
• Authentication information, where required.

Additional fields support key identification, sequence information, and subscription correlation where applicable.

Why Request Identification Matters

Consider a Manager sending a QUERY request to an Agent.

The Agent must be able to return a response that corresponds to that request.

Now consider two simultaneous requests, delayed responses, or a communication interruption.

Request identifiers allow the protocol to distinguish the relevant exchanges.

For consequential operations, request identity also becomes important for duplicate handling and safe recovery.

Authentication and Message Integrity

SAMP version 0.2 requires support for HMAC-SHA256 authentication and RFC 8785 JSON canonicalization.

Canonicalization establishes a consistent representation of message content for cryptographic processing.

Authentication protects the integrity and origin of management messages within the configured security relationship.

It does not, by itself, establish that a requested operation is authorized.

Transport

HTTP is the baseline transport, with JSON messages carried through HTTP POST.

HTTPS is required for non-localhost deployments.

WebSocket is an optional transport mapping, not a mandatory dependency.

The protocol does not require a particular agent framework, programming language, or cloud provider.

Its objective is to preserve consistent management semantics across different implementation environments.

5. The Agent Profile: A Management Contract

A SAMP Manager cannot manage an agent effectively without knowing what that agent declares and exposes.

This is the role of the SAMP Profile.

An Agent Profile describes the agent's identity, management characteristics, exposed fields, capabilities, and policy-relevant properties.

For example, a profile may tell the Manager:

• The identity and type of the managed agent.
• The software and profile versions.
• Which management fields are available.
• Which operations are supported.
• Which configuration fields are writable.
• Which execution operations are declared.
• Which management-impact class applies.
• Relevant deployment and enforcement characteristics.

Importantly, the Profile is not an unrestricted inventory of the agent's internal knowledge or reasoning state.

It defines what is exposed for management.

Profiles Can Change

AI-agent environments evolve.

A framework may be updated. Capabilities may change. A management adapter may expose additional fields.

SAMP therefore provides authenticated profile revision and sequence semantics.

These allow the Manager to distinguish a valid new profile announcement from a stale or conflicting announcement.

At the same time, frequently changing operational observations do not necessarily require a new profile.

An agent's reported uptime may change continuously.

Its declared management interface may remain unchanged.

That distinction allows SAMP to maintain a relatively stable management contract while still collecting dynamic operational information.

6. Trust and Liveness: Two Independent Questions

One of the most important design decisions in SAMP is the separation of trust from reachability.

The Manager maintains two independent state dimensions.

Trust States

• discovered
• pending
• trusted
• quarantined
• rejected
• revoked

Liveness States

• unknown
• reachable
• stale
• offline

Consider three examples.

Example A: Trusted but Offline

An authorized Agent loses network connectivity.

Its liveness may become offline, while its trust state remains trusted.

Example B: Reachable but Quarantined

An Agent responds normally to management traffic, but the Manager has placed it under investigation.

Its endpoint remains reachable.

Its trust state is quarantined.

Example C: Reachable but Not Yet Trusted

A newly discovered Agent can communicate with the Manager but has not completed the required enrollment process.

The Manager may observe its reachability without granting normal management authority.

These distinctions prevent misleading operational conclusions.

A reachable endpoint is not necessarily trusted. A trusted endpoint is not necessarily operationally healthy.

For AI-agent environments, both statements are fundamental.

7. Events and Subscriptions

Operational management is not limited to periodically requesting information.

Agents may need to report conditions as they occur.

SAMP provides PUSH for asynchronous event delivery.

It also provides SUBSCRIBE and UNSUBSCRIBE for controlling event subscriptions.

A Manager can request a subscription to supported event categories or types.

The Agent evaluates the request and, if accepted, creates a subscription with an identifier and expiration.

The subscription is owned by the authenticated Manager.

Possession of a subscription identifier does not independently grant permission to access or cancel it.

Subscriptions are time-bounded.

Core SAMP version 0.2 does not guarantee persistence of subscriptions across endpoint restarts or WebSocket reconnections.

Nor does it define unlimited event buffering or durable delivery guarantees.

These limitations are deliberate parts of the current protocol contract.

A management application that requires stronger delivery guarantees must implement or negotiate the necessary additional mechanisms.

An event notification is useful information. It is not automatically a durable audit record.

8. The Difference Between Configuration and Execution

SAMP separates configuration from execution through two PDUs.

CONFIG: Change a Declared Setting

CONFIG requests a modification to an explicitly declared writable field.

For example, a deployment might expose a configurable operational threshold.

The Manager can request a change only if the field is declared, valid, and permitted by policy.

CONFIG is not a mechanism for arbitrary modification of internal agent state.

EXEC: Invoke a Declared Operation

EXEC requests an explicitly exposed operation.

For example, an appropriate management endpoint might advertise a controlled runtime restart capability.

That operation must be declared and supported.

Its parameters must satisfy the applicable typed contract.

Its authorization must be valid.

And the final enforcement component must apply local policy.

EXEC is disabled by default.

The core protocol does not define arbitrary shell access or unrestricted natural-language execution.

Why the Separation Matters

Changing an operational parameter and triggering a consequential external action are not equivalent.

Different actions may require different authorization decisions, audit requirements, and safeguards.

SAMP recognizes those differences rather than treating every management capability as an unrestricted command interface.

9. Authorization: The Manager Is Not All-Powerful

A centralized management interface can create a dangerous assumption:

If a Manager controls the environment, perhaps every operation it requests should be accepted.

SAMP explicitly rejects that assumption.

Authentication establishes the identity associated with a management exchange.

Enrollment establishes the applicable management relationship.

Authorization determines whether a specific requested operation may proceed.

For consequential CONFIG and EXEC operations, SAMP version 0.2 requires an authorization context bound to the exact action.

That binding includes the relevant actor, target, operation, request identity, content, and policy context.

The final Policy Enforcement Point must validate the decision and apply local enforcement.

A previously authorized request cannot simply be modified and executed under the same approval.

And a conversational instruction is not itself an authorization decision.

Natural-language management interfaces must first resolve the requested operation into a deterministic structured action.

The Manager coordinates management. It does not bypass the security boundary of the managed endpoint.

SAMP defines the authorization and enforcement contract without imposing a universal organizational IAM, RBAC, ABAC, or approval-workflow system.

10. Endpoint Deployment and Failure Domains

Consider an Agent that becomes unresponsive.

A Manager may attempt to investigate or restart it.

But what happens if the SAMP management interface runs inside the same failed process?

The Manager may lose communication with both the workload and its management endpoint.

SAMP therefore supports different deployment models, including:

• Embedded management endpoints.
• Sidecars.
• Supervisors.
• AI Agent Gateways.
• Independent infrastructure-control components.

These arrangements may provide different operational guarantees.

A supervisor outside the failing workload's process boundary may remain responsive when the workload crashes.

A gateway may provide additional separation between management authority and managed workloads.

But labels alone establish nothing.

A sidecar is not automatically independent. A gateway is not automatically secure.

The real questions concern failure domains, control capabilities, enforcement authority, and whether the management and evidence paths survive the relevant failure.

SAMP allows these characteristics to be described without requiring one deployment topology for every environment.

11. What Happens When the Result Is Unknown?

Suppose a Manager sends an authorized EXEC request to restart a managed process.

The endpoint accepts the request.

The process restarts.

But the response is lost before reaching the Manager.

The Manager observes a timeout.

What happened?

The restart may have succeeded.

It may have failed.

Or the available evidence may be insufficient to determine the outcome.

SAMP version 0.2 provides recorded-operation semantics for dealing with such uncertainty.

Consequential operations have an identity and recorded outcomes.

Record revisions help distinguish subsequent updates to an operation's recorded state.

Authenticated retries are subject to duplicate protection and the applicable recorded-state constraints.

A new request identifier must not be used merely to bypass uncertainty about an earlier operation.

And later evidence may support resolution of an indeterminate outcome without repeating the original external effect.

The protocol does not promise exactly-once execution for arbitrary external actions.

Instead, it requires implementations to recognize the difference between an unknown outcome and a failed operation.

Never convert uncertainty into certainty merely because a management interface needs to display a result.

This principle is essential in distributed operational systems.

12. How Much of SAMP Must an Implementation Support?

Not every management deployment needs execution authority.

Some environments require only discovery and monitoring.

Others need subscriptions or controlled configuration.

SAMP therefore defines four additive conformance tiers.

These tiers identify protocol support requirements.

They do not eliminate mandatory security, validation, or error-handling requirements.

Nor does support for CONFIG or EXEC mean that those operations must be enabled in a particular deployment.

Conformance is evaluated separately for Manager and Agent endpoint implementations.

This approach allows deployments to expose different management capabilities without silently weakening the core protocol contract.

13. From SAMP Architecture to AgMS

The Agent Management System (AgMS) is an experimental application developed to explore SAMP-oriented management of heterogeneous AI-agent environments.

Inspired by traditional Network Management Systems, AgMS provides practical experience with agent integration, operational visibility, management interactions, event handling, and failure scenarios.

It demonstrates why a common management-plane architecture is useful when different AI-agent frameworks must be observed through a consistent operational interface.

However, AgMS remains in Alpha development.

Its experimental implementation experience should not be confused with independent validation or complete SAMP version 0.2 conformance.

The broader engineering objective is to determine whether the protocol's management relationship can be implemented consistently across independently developed systems.

Explore SAMP Implementations

14. What SAMP Does Not Attempt to Do

One of the challenges of protocol engineering is knowing where to stop.

SAMP is not designed to become a universal AI-agent platform.

It does not define:

• How agents reason or plan tasks.
• Which models they use.
• How they invoke external tools.
• How agents communicate with each other.
• How organizations design their complete authorization policies.
• A universal multi-manager federation system.
• Fleet-wide transactional orchestration.

Those responsibilities belong to other systems and protocol layers.

SAMP defines the operational management relationship.

It can coexist with MCP, A2A, OpAMP, OpenTelemetry, and external authorization or verification systems.

The objective is interoperability through clear boundaries, not unnecessary replacement of existing technology.

Conclusion: Managing the Agent, Not Its Intelligence

The architecture of SAMP is intentionally straightforward.

A Manager maintains the operational management relationship.

An Agent exposes a declared, authenticated management interface.

The protocol defines how these components exchange information, establish trust, report events, request changes, and handle uncertain outcomes.

The complexity lies not in the number of PDU types.

It lies in defining what each exchange can legitimately establish.

A heartbeat establishes endpoint reachability, not workload correctness.

Authentication establishes message authenticity, not unrestricted authority.

A quarantine request is not proof of isolation.

A successful protocol exchange is not necessarily proof of an external effect.

And a timeout is not evidence that an operation never occurred.

These distinctions make the difference between a management interface that merely displays information and a management plane that can support operationally accountable decisions.

The objective of SAMP is not to control how AI agents think.

It is to define how heterogeneous AI agents can be managed, observed, and controlled under explicit operational and security constraints.

That is the purpose of the SAMP Management Plane.

Technical References

• SAMP Internet-Draft, Revision -04
• SAMP Protocol Overview
• SAMP Implementations
• Contribute to SAMP

Technical feedback: [email protected]

SAMP Engineering Notes is a technical article series exploring the architecture, security, implementation, and interoperability challenges of the Simple Agent Management Protocol.

Previous: From SNMP to SAMP: Managing AI Agents.

Next: Trust, Liveness and Failure Domains.