Docs / Reference

Invocation envelope fields

Invocation envelopes carry the fields a host needs to validate subject, capability, mode, payload, requested time, and correlation.

Plain English

The invocation envelope is the request wrapper around the capability payload.

Why it exists

A host cannot safely authorize, trace, or replay a capability call if subject identity and correlation are implicit.

Formal definition

An InvocationEnvelope is a structured request containing invocation identity, capability identity, mode, correlation context, subject, payload, requested time, and optional metadata.

Concrete example

Ground the concept before the schema.

Planning Agent invokes schedule_technician with session-abc correlation and job_context payload.

invoke.json
json
{  "invocation_id": "inv_session_abc_001",  "capability_id": "schedule_technician",  "version": "1.0.0",  "mode": "sync",  "correlation": { "correlation_id": "session-abc" },  "subject": {    "id": "agent://planning-assistant",    "roles": ["dispatcher"]  },  "payload": {    "job_id": "job_456",    "window": "tomorrow"  },  "requested_at": "2026-06-16T15:14:20.000Z"}

Developer reference

Invocation envelope field reference

Every invocation should make caller intent and replay context explicit before execution.

FieldTypeProtocol meaning
invocation_idstring

Unique request identity preserved in results and evidence.

capability_idstring

Capability selected from a compatible manifest or registry entry.

versionstring | null

Requested capability version, when callers need a specific contract.

modesync | async | stream | fire_and_forget

Invocation mode that must be supported by the capability descriptor.

correlation.correlation_idstring

Stable ID used to connect invocation, evidence, replay, and telemetry.

subjectobject

Caller identity and caller-local attributes used by host policy.

payloadobject

Capability-specific inputs validated against the capability contract.

requested_atdatetime

Caller-side request timestamp used for audit and replay context.

metadataobject

Optional extension area for implementation-specific request metadata.

Relationships

Where this sits in the protocol.

Each concept should explain its neighbors so implementation teams can preserve the boundary across manifests, invocation, evidence, and tests.

Reference pages turn protocol concepts into implementation checks.

Field names, outcome codes, and conformance cases should stay stable across hosts.

Examples should map every field back to capability, host, policy, context, or evidence.

Visual model

  1. 01Read the field or code before implementation.
  2. 02Map it into manifest, invocation, outcome, or evidence behavior.
  3. 03Add route, conformance, or unit coverage for each failure-sensitive field.

Implementation notes

  • Prefer explicit protocol fields over framework-specific inference.
  • Treat absent required fields as malformed protocol input.
  • Keep examples close to the failure cases they are meant to prevent.

Common mistakes

  • Letting transport status codes carry protocol meaning alone.
  • Hiding required protocol state in logs or application glue.
  • Testing only successful invocations.

Related concepts

Keep reading through the boundary.

Invocation →Context →Outcome codes →