SAMP Engineering Notes #10

Agent Profiles as Versioned Management Contracts

How SAMP handles profile revisions, authenticated announcements, schema validation, and management compatibility without confusing declared capabilities with operational authority.

1. The Problem: An Agent Changes While the Manager Is Watching

Consider an AI agent deployed in a security operations environment.

Initially, its management interface exposes only observational capabilities. The SAMP Manager can inspect operational status, collect selected metrics, and receive events.

Later, the agent's management adapter is upgraded.

The new release introduces an additional configuration field, changes a declared field constraint, and exposes a new management operation.

The agent is still the same logical entity. Its management contract, however, has changed.

Now consider a second complication.

The Manager receives the updated profile, but an older DISCOVER announcement, delayed by the network or retransmitted after a timeout, arrives afterward.

What should happen?

A naïve implementation might accept the last announcement received and overwrite the current registry.

The result would be a management system operating against outdated declarations.

This is not merely an inventory problem. The Manager could make decisions using incorrect field types, obsolete capability information, or an outdated execution policy.

A management protocol must distinguish the latest authenticated contract from the latest message delivered by the network.

SAMP addresses this problem through explicit profile identity, revision, sequence, validation, and enrollment-bound ordering rules.

2. A Profile Is More Than an Agent Description

A SAMP Profile defines the interface through which a managed agent presents itself to the management plane.

It includes identity information, declared management fields, operational capabilities, policy declarations, and relevant deployment metadata.

The distinction is important.

An agent's internal implementation may change independently of its management interface. Conversely, a small adapter update may change the management contract without changing the underlying AI model.

The Manager therefore needs to understand the declared interface rather than infer management behavior from the agent's framework, model family, or software name.

A valid profile provides a structured description of what the endpoint exposes.

It does not prove that the agent is trustworthy, that its claims are truthful, or that every advertised operation is currently authorized.

Those are separate management decisions.

3. Three Different Versioning Concepts

SAMP v0.2 distinguishes three concepts that should not be confused.

There is a fourth, independent value: the SAMP protocol envelope version.

In the current Experimental specification, the envelope uses version 0.2, while the base profile format retains profile_version = "0.1".

These values describe different things. Updating the protocol envelope does not automatically update the profile format.

The distinction between revision and sequence is equally important.

profile_revision is an opaque identifier. It is not a version number that a Manager may sort lexically or numerically.

profile_sequence is a monotonically increasing integer within the authenticated enrollment context.

The initial accepted profile uses sequence 1. Each changed profile announcement requires a new revision and a strictly greater sequence.

Gaps are permitted, allowing multiple local changes to be combined into one consistent announcement.

This means that a Manager does not have to guess which profile is newer based on timestamps, software version strings, or the apparent ordering of revision names.

The protocol provides an explicit ordering mechanism.

4. Why an Immutable Snapshot Matters

A profile revision identifies one announced snapshot.

Suppose an agent initially announces a profile exposing read-only management fields.

Its authenticated announcement is accepted as:

Following a legitimate update, the endpoint announces:

The Manager validates the new announcement and, if accepted, records it as the current authoritative profile.

The old profile must not become authoritative again simply because its announcement is retransmitted.

The Manager retains the accepted sequence, revision, and authenticated canonical profile digest.

The digest is calculated over the complete profile object using RFC 8785 JSON canonicalization followed by SHA-256.

This allows the Manager to distinguish an identical announcement from a conflicting one.

The protection is not based on arrival order alone. It combines authenticated identity, enrollment context, profile ordering, and content identity.

5. What Happens When Announcements Arrive Out of Order?

Consider an endpoint whose current authoritative profile is profile-b, sequence 2.

The Manager may encounter several situations.

An important exception applies to genuine recorded DISCOVER retries. A lower-sequence announcement that matches an authorized, retained historical request may receive its original recorded outcome in a fresh response envelope, without reinstalling or modifying the current authoritative profile. An unseen older announcement remains subject to profile_stale.

An important rule follows:

A higher sequence makes an announcement a candidate for acceptance, not an automatically trusted replacement.

The Manager must still validate the profile and apply relevant authorization policy.

For concurrent announcements from the same authenticated identity, profile installation must be serialized.

Acceptance atomically replaces the previous committed profile-ordering record.

Neither a delayed duplicate nor a rejected candidate may overwrite the last valid snapshot.

These behaviors make profile handling deterministic even when message delivery is delayed, duplicated, or reordered.

6. Profile Validation Is a Contract Enforcement Problem

Versioning alone is insufficient.

A Manager also needs to understand whether the announced declarations form a valid management interface.

SAMP v0.2 uses typed field declarations.

The required base category is system, which includes:

• system.status: A non-empty self-reported status string.
• system.uptime: A non-negative integer representing workload uptime in seconds.
• system.version: A non-empty version string consistent with agent_version.
• system.last_seen: An RFC 3339 UTC timestamp representing an agent-observed interaction.

These fields are accompanied by required type declarations.

Additional categories and fields may be exposed, but declared categories follow a closed-object model.

An undeclared value inside a declared category is invalid. Required fields cannot silently disappear. Types and constraints must be respected.

The declaration model also supports recursive constraints for objects and arrays, permitted values, numeric boundaries, string lengths, and explicit nullability.

This matters because a Manager must be able to distinguish a legitimate interface change from malformed or ambiguous data.

For example, an upgrade that changes a declared integer into an object changes the interpretation of that management field.

The Manager cannot safely continue using the previous declaration while accepting values from the new representation.

It must evaluate the newly announced contract.

Profile validation does not establish that the reported information is true. It establishes that the information conforms to the declared interface and protocol requirements.

7. Not Every Operational Change Requires a New Profile

A fundamental implementation distinction is the separation between management declarations and live operational observations.

An agent's uptime increases continuously.

Its operational status may move from normal to degraded.

Its most recent interaction timestamp changes.

These observations do not necessarily change what the management interface exposes.

SAMP therefore allows fresh runtime readings to be returned through QUERY or PUSH without requiring a new profile revision for every observation.

For example:

• The declared field system.uptime remains an integer.
• A QUERY returns a newer uptime value.
• The management contract remains unchanged.
• No profile reannouncement is necessary solely because the observed value changed.

However, if the endpoint sends a new DISCOVER profile object containing changed values, that announced object is different and requires a new revision and greater sequence.

This is why rapidly changing readings should generally remain in operational queries and events rather than repeatedly modifying the announced profile.

A useful engineering principle emerges:

Use profile announcements to communicate authoritative management snapshots. Use operational observations to communicate changing runtime conditions.

A stable profile is not evidence of a healthy workload, just as a responsive management endpoint is not proof that the underlying agent is successfully executing its tasks.

8. QUERY Must Be Bound to the Expected Contract

Profile revisions also affect ordinary management queries.

Consider a Manager that has accepted profile-a and sends a QUERY for a field declared in that snapshot.

Before the query is evaluated, the Agent switches to profile-b, whose declarations differ.

Without revision binding, the endpoint might interpret the requested field according to the new profile while the Manager expects the old one.

The resulting response could be syntactically valid but semantically inconsistent.

SAMP v0.2 addresses this by requiring an expected_profile_revision in core QUERY requests.

The endpoint compares that value against its current authoritative revision before resolving any requested fields.

If the revisions differ, the endpoint returns profile_revision_mismatch rather than evaluating the request against a different contract.

Successful QUERY responses identify the profile revision used for evaluation.

They also distinguish three outcomes for individual requested fields: a present value, a declared optional field that is absent, and an unknown or unexposed field.

Explicit JSON null is different from absence and is permitted only when the corresponding declaration allows it.

These distinctions prevent ambiguous observations from being silently interpreted as valid measurements.

For the Manager, a revision mismatch indicates that its knowledge of the interface needs reconciliation.

It is not permission to retry blindly under a different contract.

9. Extending a Profile Without Silently Changing the Protocol

Heterogeneous AI-agent environments will inevitably require specialized management information.

A security-analysis agent, a code-generation agent, and an infrastructure automation agent may expose different operational characteristics.

SAMP permits optional extension-support advertisement through the supported_extensions profile metadata.

An extension is identified by an explicit pair:

extension_id + extension_version

The identifier names the extension family; the version identifies its exact specification.

SAMP v0.2 does not infer compatibility from URI naming, semantic-version ordering, or implicit version ranges.

An advertised extension also does not automatically become active.

The Manager must explicitly recognize the identified extension and apply local policy before interpreting its content.

The extension advertisement is discovery metadata, not an authorization mechanism or a general-purpose negotiation handshake.

This prevents a management endpoint from introducing new execution behavior merely by declaring that it supports an additional extension.

The result is controlled extensibility: implementations may introduce specialized contracts without silently redefining the core protocol or bypassing its management boundaries.

10. Restart and Recovery Must Not Roll Back the Contract

A less obvious problem occurs when a Manager restarts or loses part of its persistent state.

Suppose the latest accepted profile had sequence 8.

After a restart, an old authenticated announcement carrying sequence 5 arrives.

If the Manager has lost its ordering history and accepts the announcement as a new initial profile, the old management contract may be reinstated.

Valid message authentication alone does not solve this problem.

SAMP requires profile-ordering state to remain bound to the authenticated Agent identity and its enrollment context.

An ordinary restart, timeout, credential rotation within the same enrollment, or replay-cache expiration does not reset profile_sequence.

If the Manager loses authoritative ordering state, it must recover an integrity-protected record known to represent the latest committed boundary.

Otherwise, affected profile admission remains fenced, or an explicitly authorized enrollment replacement must occur.

An enrollment replacement requires fresh operational credentials and a distinct authentication context. Only after a valid replacement may the new enrollment begin its own sequence at 1.

This is a deliberately conservative design.

A management system that has lost the evidence needed to establish the latest valid contract should not recreate that certainty through guesswork.

11. An Implementation Test Worth Running

The versioning and ordering rules can be evaluated without introducing a complex AI workload.

An independent SAMP implementation can perform the following experiment:

1. Establish an authenticated enrollment and accept an initial valid profile at sequence 1.
2. Announce a changed, valid profile at sequence 2.
3. Retransmit the original sequence-1 announcement and verify that it cannot overwrite sequence 2.
4. Repeat sequence 2 with different content and verify conflict rejection.
5. Attempt an invalid higher-sequence profile and verify that the accepted snapshot remains unchanged.
6. Send a QUERY referencing the obsolete revision and verify revision-mismatch handling.
7. Restart the Manager and verify that its committed ordering boundary survives.
8. Simulate loss of authoritative ordering state and verify fail-closed recovery rather than implicit reset.

These are proposed test scenarios derived from the specification, not a claim that this exact test suite has already been executed successfully in an independent implementation.

They also expose an important interoperability question: do different implementations reach the same observable decisions when presented with identical authenticated profile histories?

That is more meaningful than demonstrating that two implementations can exchange a single successful DISCOVER message.

12. The Engineering Lesson

In traditional network management, operators often distinguish between device configuration, software version, supported features, and changing operational counters.

AI-agent management requires similar discipline, but the managed interface may evolve independently of the agent's underlying framework or reasoning system.

SAMP does not require a Manager to understand how an agent thinks.

It requires the Manager to understand which management contract has been authenticated, validated, accepted, and made authoritative.

The essential distinctions are straightforward:

A profile version identifies a format.

A profile revision identifies a snapshot.

A profile sequence establishes announcement order.

A capability declaration identifies support, not permission.

An operational observation describes a reading, not necessarily a contract change.

Together, these distinctions allow SAMP implementations to reason consistently about changing management interfaces without relying on message arrival order, implicit compatibility assumptions, or unsupported authority claims.

The result is not automatic trust in an AI agent.

It is something narrower and operationally valuable: a well-defined basis for knowing which management contract the system is currently using.

Specification Reference

This Engineering Note discusses the Experimental SAMP v0.2 specification, particularly Sections 5.1–5.6, 5.13, 5.13.1, and 8.2.3 of:

Simple Agent Management Protocol (SAMP), draft-efstathiou-samp-agent-management-04

SAMP remains an individual Internet-Draft, not an approved IETF standard. The Internet-Draft is authoritative for protocol requirements; this article provides engineering explanation and illustrative implementation scenarios.

Stelio E. Efstathiou

SAMP Protocol Project