Struct AgentEnvelope 

pub struct AgentEnvelope {

    pub kind: AgentKind,
    pub record: Option<RecordId>,
    pub conversation: ConversationId,
    pub source: AgentId,
    pub target: Option<AgentId>,
    pub cause: Option<RecordId>,
    pub cause_at: Option<LogPosition>,
    pub correlation: Option<CorrelationId>,
    pub channel: Option<ChannelId>,
    pub idempotency_key: Option<IdempotencyKey>,
    pub deadline_micros: Option<u64>,
    pub sequence: Option<u64>,
    pub last: bool,
    pub finish_reason: Option<String>,
    pub task_state: Option<TaskState>,
    pub operation: Option<String>,
    pub tool: Option<String>,
    pub usage: Option<TokenUsage>,
    pub metadata: Option<BTreeMap<String, Value>>,
    pub must_understand: u64,
    pub body: Vec<u8>,
    pub signature: Option<Signature>,
}

The AGDX envelope: one CBOR named-field decode unit per agent message.

Field semantics, the per-kind validity matrix, and the caps are enforced by validate, and the per-kind constructors stamp the required shape. Routing fields (conversation, target, content type) are also stamped as typed headers so projections and plain Iggy consumers work without decoding bodies. The envelope is the typed, versioned form of what the headers say.

metadata is the AGDX-native extension slot, distinct from headers (the substrate and observability dictionary) and body (the content). Foreign metadata (A2A metadata, MCP _meta) never maps into it. It tunnels whole inside body, keeping bridge round trips byte-identical.

Fields

kind: AgentKind

record: Option<RecordId>

Producer-assigned record identity, required on every kind except chunk (chunks are identified by channel + sequence, saving the id bytes and a clock-and-entropy call per token).

conversation: ConversationId

Also the partition key.

source: AgentId

Agent-authorship claim (see the module docs).

target: Option<AgentId>

Routing refinement within a shared topic. The topic itself is the primary address. Consumer-side filtering by target is a convenience, not a confidentiality control. The topic is the boundary.

cause: Option<RecordId>

The causal parent’s record id: the identity half of the causal pointer, stable across replication.

cause_at: Option<LogPosition>

The causal parent’s log position: the locator half, an O(1) dereference for raw log walkers, deployment-local.

correlation: Option<CorrelationId>

Request/reply pairing. A2A task identity maps onto it.

channel: Option<ChannelId>

Chunk grouping when many streams run under one correlation.

idempotency_key: Option<IdempotencyKey>

deadline_micros: Option<u64>

Drop-dead time, epoch micros. On a stream-opening message it is also the reader-local abandonment bound: the producer knows its own model timeout, the consumer would be guessing.

sequence: Option<u64>

Chunk ordering within a channel.

last: bool

Terminal flag: the final chunk of a stream / the final task update. false is equivalent to absence and is skipped on encode, so only true has protocol meaning. Maps one-to-one onto A2A’s final.

finish_reason: Option<String>

Why a stream or response ended (OTel finish-reason vocabulary: stop, length, content_filter, tool_call, …). A string deliberately: that vocabulary belongs to OTel and the providers, not to us.

task_state: Option<TaskState>

operation: Option<String>

OTel gen_ai.operation.name value (chat, execute_tool, …). On status it is the required discriminator (task, card, progress).

tool: Option<String>

OTel gen_ai.tool.name, for tool commands and results.

usage: Option<TokenUsage>

metadata: Option<BTreeMap<String, Value>>

AGDX-native scalar extension context. Never foreign metadata.

must_understand: u64

Must-understand marker: a bitset of feature bits a receiver MUST understand to process this message correctly (see features). A receiver that sees a set bit it does not implement MUST reject or dead-letter the message rather than mis-handle it (unmet_requirements). 0 (the default, skipped on the wire so pre-marker records stay byte-identical) means “ignore anything you don’t understand”, the open-world default. This lets one message demand strict handling of a new feature without a whole-envelope version bump (a must_understand marker).

body: Vec<u8>

The content, codec per the agdx.ct header. Default-empty and skipped when empty. The validity matrix says which kinds require it.

signature: Option<Signature>

A detached signature over the canonical encoding of this envelope with the signature field absent, domain-separated by SIGNATURE_DOMAIN. Opt-in: absent (the open-world default, skipped on the wire so an unsigned record stays byte-identical) means an unsigned record. Verification is SDK-side against a per-agent key registry, so the wire crate stays crypto-free. A signature may ride any kind (no matrix row, like metadata).

Implementations

impl AgentEnvelope

pub fn requiring(self, bits: u64) -> Self

Declare that a receiver MUST understand the feature bits to process this message. Bits a receiver lacks make it reject the message (unmet_requirements). Absent bits are ignore-if-unknown. Additive builder method.

pub fn unmet_requirements(&self, understood: u64) -> u64

The subset of this message’s must_understand bits NOT present in the receiver’s understood set. Non-zero means the receiver cannot safely process the message and must reject or dead-letter it rather than mis-handle a feature it does not implement.

pub fn command( record: RecordId, conversation: ConversationId, source: AgentId, correlation: CorrelationId, body: Vec<u8>, ) -> Self

A command: expects a reply or effect, so correlation is required.

pub fn response( record: RecordId, conversation: ConversationId, source: AgentId, correlation: CorrelationId, body: Vec<u8>, ) -> Self

A response: the paired answer to a command (same correlation).

pub fn event( record: RecordId, conversation: ConversationId, source: AgentId, body: Vec<u8>, ) -> Self

An event: expects nothing.

pub fn chunk( conversation: ConversationId, source: AgentId, correlation: CorrelationId, channel: ChannelId, sequence: u64, body: Vec<u8>, ) -> Self

A chunk of the stream channel, ordered by sequence. Mark the final one with terminal.

pub fn status( record: RecordId, conversation: ConversationId, source: AgentId, operation: impl Into<String>, ) -> Self

A status signal discriminated by operation (task, card, progress). Task updates additionally require correlation and task_state (use the with-setters).

pub fn error( record: RecordId, conversation: ConversationId, source: AgentId, correlation: CorrelationId, body: Vec<u8>, ) -> Self

An error terminal for correlation. body is the encoded AgentErrorBody.

pub fn with_target(self, target: AgentId) -> Self

Narrow delivery to one agent within a shared topic.

pub fn with_cause(self, cause: RecordId, cause_at: Option<LogPosition>) -> Self

Stamp the causal parent: its record id (identity) and, when known, its log position (locator). A handler has both for free from the message it is replying to.

pub fn with_correlation(self, correlation: CorrelationId) -> Self

Pair this message with a correlation id. Required on command, response, error, and chunk. Optional on event and non-task status.

pub fn with_idempotency_key(self, key: IdempotencyKey) -> Self

Attach a business idempotency key (commands, responses, events only).

pub fn with_deadline_micros(self, deadline_micros: u64) -> Self

Declare the drop-dead time (and, on a stream-opening message, the abandonment bound).

pub fn terminal(self, finish_reason: impl Into<String>) -> Self

Mark this message terminal (last = true), with the reason the stream or response ended.

pub fn with_task_state(self, state: TaskState) -> Self

Attach a task state. Status task updates require it. Responses and errors may carry it as the one-message terminal convenience.

pub fn with_operation(self, operation: impl Into<String>) -> Self

Set the OTel operation name.

pub fn with_tool(self, tool: impl Into<String>) -> Self

Set the OTel tool name.

pub fn with_usage(self, usage: TokenUsage) -> Self

Attach token accounting (advisory).

pub fn with_metadata( self, key: impl Into<String>, value: impl Into<Value>, ) -> Self

Add one AGDX-native metadata entry.

pub fn with_signature(self, signature: Signature) -> Self

Attach a detached Signature over this envelope. The SDK signs the canonical encoding with the signature absent and domain separator SIGNATURE_DOMAIN, so the field is set last. A signature may ride any kind.

Trait Implementations

impl Clone for AgentEnvelope

fn clone(&self) -> AgentEnvelope

Returns a duplicate of the value.

fn clone_from(&mut self, source: &Self)

Performs copy-assignment from source.

impl Debug for AgentEnvelope

fn fmt(&self, f: &mut Formatter<'_>) -> Result

Formats the value using the given formatter.

impl<'de> Deserialize<'de> for AgentEnvelope

fn deserialize<__D>(__deserializer: __D) -> Result<Self, __D::Error>

where __D: Deserializer<'de>,

Deserialize this value from the given Serde deserializer.

impl PartialEq for AgentEnvelope

fn eq(&self, other: &AgentEnvelope) -> bool

Equality operator ==.

fn ne(&self, other: &Rhs) -> bool

Inequality operator !=.

impl Serialize for AgentEnvelope

fn serialize<__S>(&self, __serializer: __S) -> Result<__S::Ok, __S::Error>

where __S: Serializer,

Serialize this value into the given Serde serializer.

impl StructuralPartialEq for AgentEnvelope