Agent Envelope Exchange (AEE): A Minimal JSON Envelope Format for Inter-Agent Communication

5.1. Identifier Format

The RECOMMENDED identifier format is:¶

<type>.<name>

where "type" indicates the entity category and "name" is a locally unique identifier within that category. Implementations MAY use any unique string, but the typed format improves debuggability and log readability.¶

5.2. Common Type Prefixes

The following type prefixes are defined as conventions. This list is not exhaustive; implementations MAY define additional prefixes.¶

agent.*

Autonomous agents (e.g., "agent.backup_auditor", "agent.code_reviewer").¶

service.*

Traditional (non-agent) services (e.g., "service.billing", "service.auth").¶

human.*

Human participants (e.g., "human.adam", "human.ops_lead").¶

bus.*

Broadcast channels or topic-based routing targets (e.g., "bus.ops", "bus.alerts").¶

5.3. Causality Tracing Across Entity Types

When a human initiates a task that cascades through multiple agents, the full causality chain is traceable through the combination of "from", "to", "corr", and "reply_to" fields. For example, a chain such as "human.adam" to "agent.router" to "agent.reviewer" to "service.linter" maintains complete provenance regardless of entity type at each hop.¶

7.1. MVE-Required (Schema-Valid)

The Minimal Viable Envelope (MVE-Required) tier includes all fields required by the JSON Schema:¶

• "v"¶
• "id"¶
• "ts"¶
• "type"¶
• "from"¶
• "to"¶
• "intent"¶
• "corr"¶
• "priority"¶
• "payload"¶

A system emitting envelopes with all 10 MVE-Required fields is fully schema-valid and interoperable with any AEE-compliant consumer. A system MAY claim MVE-Required compliance if:¶

1. It emits envelopes with all 10 required fields.¶
2. Those envelopes validate against the AEE v1 JSON Schema.¶
3. The "reply_to" field is non-null for "result" and "error" types.¶

MVE-Required certification attests to structural compliance only. It does not certify payload schema conformance, semantic correctness of intents, or support for the "aee.*" protocol intents defined in Section 9.¶

7.2. MVE-5 (Log-Friendly)

For logging, telemetry, and observability-only contexts, a 5-field subset is recognized:¶

• "v"¶
• "id"¶
• "type"¶
• "from"¶
• "intent"¶

MVE-5 is NOT schema-valid AEE. It is a convenience envelope for systems that only emit logs or telemetry and do not participate in request/response flows. MVE-5 envelopes:¶

• Can be parsed by AEE-aware log aggregators.¶
• Cannot be used for task/result correlation (missing "corr" and "reply_to").¶
• SHOULD NOT be sent to agents expecting full envelopes.¶

9.1. Naming Conventions

The RECOMMENDED naming format uses flexible dotted notation:¶

<domain>.<subdomain>.<noun>.<verb>

Examples:¶

• "ops.network.port.probe"¶
• "ops.backup.status.check"¶
• "infra.proxmox.vm.create"¶
• "docs.summarize.with_citations"¶

Verbs SHOULD be explicit (e.g., "check", "probe", "create", "summarize"). Implementations SHOULD avoid overloading a single intent with multiple optional behaviors. Intent schemas MAY be versioned independently of the AEE envelope specification.¶

If two agents cannot agree on an intent identifier, they do not share semantics. The absence of a recognized intent is not an error; it simply indicates that the agents lack a shared vocabulary for that operation.¶

9.2. Reserved Namespace: aee.*

The "aee.*" namespace is reserved for protocol negotiation and context retrieval. These intents enable agents to discover capabilities, fetch context, and validate payloads without custom integration. They are protocol primitives, not orchestration mechanisms.¶

The following core intents are defined:¶

Implementations claiming AEE compliance are not required to implement all "aee.*" intents. However, "aee.status.ping" SHOULD be supported by all agents to enable basic liveness detection.¶

Application-specific intents MUST NOT use the "aee.*" namespace. If a use case requires scheduling, workflow, or orchestration semantics, those intents belong in an application namespace (or in a companion protocol such as AOCL [AOCL]).¶

9.3. Intent Schema Publishing

AEE does not standardize the "payload" field's internal structure. Instead, each intent publishes separate JSON Schema documents for its "task", "result", and "error" payload variants. The RECOMMENDED file layout is:¶

envelope/aee-v1.schema.json
intents/<intent>.task.schema.json
intents/<intent>.result.schema.json
intents/<intent>.error.schema.json

AEE does not require a centralized intent registry. Communities MAY publish intent schemas in version-controlled repositories, package registries, or any other distribution mechanism appropriate to their ecosystem.¶

10.1. Rationale: Avoiding Nested Envelopes

Embedding full envelopes inside payloads creates several problems:¶

• Matryoshka bloat: Deeply nested structures grow with each hop in a multi-agent workflow, consuming storage and bandwidth.¶
• Token collapse: Large language models (LLMs) processing nested envelopes waste context window tokens on redundant structural metadata.¶
• Signature ambiguity: When envelopes are nested, it becomes unclear which envelope's signature is authoritative -- the outer or the inner.¶

10.2. The payload.references Array

When referencing prior envelopes, implementations SHOULD use a "references" array within the payload:¶

{
  "payload": {
    "references": [
      {
        "id": "01JFB2R1JZKQ9V3K8W8Y9W1F2A",
        "corr": "01JFB2QX0K8X5K6ZJ9G2C0C1MW",
        "type": "aee.envelope",
        "locator": "store://envelopes/01JFB2R1JZKQ9V3K8W8Y9W1F2A",
        "hash": "sha256:a1b2c3..."
      }
    ]
  }
}

Each reference object contains the following fields:¶

id (REQUIRED)

The referenced envelope's "id" value.¶

corr (OPTIONAL)

The correlation ID for additional context.¶

type (REQUIRED)

The reference type. For envelope references, the value MUST be "aee.envelope".¶

locator (OPTIONAL)

A URI or path that can be used to retrieve the full referenced envelope, for example via the "aee.context.fetch" intent.¶

hash (OPTIONAL)

A content hash (e.g., "sha256:...") for integrity verification of the referenced envelope.¶

To retrieve the full envelope behind a reference, consumers SHOULD use the "aee.context.fetch" protocol intent (see Section 9).¶

10.3. Exception: Archival and Forensic Snapshots

When creating immutable audit logs or forensic snapshots, embedding full envelopes as inert blobs within a "result" payload is acceptable. These embedded envelopes are historical records, not active routing participants. Implementations MUST NOT attempt to route or process embedded archival envelopes as live messages.¶

11.1. Replay Attacks and Correlation ID Uniqueness

Each AEE envelope carries a unique "id" field and a "corr" field linking related messages. If message identifiers are predictable or reused, an attacker could replay previously captured envelopes to trigger duplicate work or corrupt workflow state. Implementations MUST generate "id" values using cryptographically random or lexicographically-sortable unique identifiers (e.g., ULIDs or UUIDs [RFC4122]). Consumers SHOULD maintain a deduplication window and reject envelopes with previously seen "id" values within that window. The "ts" field SHOULD be checked against a reasonable clock-skew tolerance to detect stale replays.¶

11.2. Signature Verification and Trust Model

The "sig" field is OPTIONAL, meaning that unsigned envelopes are valid per this specification. Deployments operating in environments where message authenticity is critical MUST require signatures and establish a trust model for key distribution. Ed25519 is RECOMMENDED for asymmetric signatures due to its performance characteristics and resistance to implementation pitfalls. When signatures are present, consumers MUST verify them before processing the envelope. A failed signature verification MUST result in rejection of the envelope.¶

This specification does not define a public key infrastructure (PKI) or key exchange mechanism. Deployments SHOULD document their key management procedures, including key rotation schedules, revocation mechanisms, and the scope of trust for each key identifier ("kid").¶

11.3. Envelope Integrity Without Signatures

In deployments where the "sig" field is not used, envelope integrity depends entirely on the security properties of the transport layer. If envelopes are carried over an unencrypted or unauthenticated channel, any intermediary can modify envelope fields -- including "from", "to", "intent", and "payload" -- without detection. Deployments that do not use envelope-level signatures MUST ensure that the transport layer provides adequate integrity and authentication guarantees (e.g., TLS with mutual authentication). For tamper-evident recording of envelope exchanges, the companion VOLT protocol [VOLT] defines cryptographic hash chains that can provide post-hoc verification of envelope integrity.¶

11.4. Privacy of Payload Contents

AEE envelopes carry arbitrary payload data that may include personally identifiable information (PII), credentials, internal system details, or other sensitive content. The envelope format does not provide payload encryption. Implementations handling sensitive data SHOULD encrypt payloads at the application layer or ensure that the transport provides confidentiality (e.g., TLS). The "requires" field MUST NOT be used to carry secrets; credentials should be transmitted through secure side-channels rather than embedded in envelope metadata.¶

The logging guidance in Section 6 (rule 8) recommends logging several envelope fields for observability. Implementations MUST ensure that logged fields do not inadvertently expose sensitive payload contents. The "intent" field, while not typically sensitive, may reveal operational patterns; deployments SHOULD consider the information leakage implications of intent names in log aggregation systems.¶

11.5. Trust Boundaries Between Agents

AEE entity identifiers (see Section 5) are self-asserted: the "from" field is populated by the sender, and there is no built-in mechanism to verify that the claimed sender identity is authentic. In multi-tenant or cross-organizational deployments, a malicious agent could impersonate another agent by setting an arbitrary "from" value. Deployments MUST implement identity verification at trust boundaries, either through envelope signatures (see Section 8), transport-layer authentication, or a gateway that validates sender identity before forwarding envelopes.¶

When envelopes cross trust boundaries (e.g., from an internal agent network to an external partner's agents), implementations SHOULD validate all envelope fields at the boundary, strip or redact sensitive payload content, and apply allowlist-based intent filtering to prevent unauthorized operations.¶

11.6. Denial of Service via Priority Field Abuse

The "priority" field allows senders to signal message urgency. A malicious or misconfigured agent could set all messages to "urgent" priority, starving normal-priority messages of processing resources. Implementations SHOULD enforce per-sender priority quotas or rate limits. Infrastructure components SHOULD NOT blindly trust the "priority" field from untrusted sources; instead, they SHOULD apply policy-based priority assignment or capping at trust boundaries.¶

Similarly, the "requires" field's "timeout_ms" value could be abused to hold resources for extended periods. Consumers SHOULD enforce maximum timeout values regardless of the requested timeout, and SHOULD release resources promptly when timeouts expire.¶