Docs / Concepts

Invocation

An invocation is a structured request to run a capability with subject attributes, mode, payload, requested time, and correlation.

Plain English

An invocation is the moment a caller asks a host to do the named thing.

Why it exists

Sensitive capability calls need more than a function call shape; they need identity, intent, policy checks, timeout behavior, and outcomes.

Formal definition

An invocation is a protocol envelope that names the capability, carries payload and subject context, declares mode, preserves correlation, and receives a structured result.

Concrete example

Ground the concept before the schema.

Planning Agent invokes schedule_technician with job_context and receives either Confirmed Appointment or approval_required.

schedule_technicianInvokable

Finds an available qualified technician and reserves a service window.

host: ServiceOpsHostpolicy: approval_requiredv1.0.0

Policy boundary

Approval required

manager_approval

A manager must approve technician scheduling before the host returns a confirmed appointment.

Invocation trace

  1. 01 Actor

    Planning Agent

  2. 02 Capability

    schedule_technician

  3. 03 Host

    ServiceOpsHost

  4. 04 Policy

    manager_approval

  5. 05 Context

    job_context

  6. 06 Result

    Confirmed Appointment

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"}

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.

Invocation depends on manifest discovery and compatibility checks.

Policy can deny or pause an invocation before execution.

Evidence records accepted or denied invocation outcomes.

Visual model

  1. 01Actor sends capability_id and payload.
  2. 02Host validates lifecycle, permission, and payload.
  3. 03Host returns a structured success, denial, or error outcome.

Implementation notes

  • Require correlation IDs for replay and debugging.
  • Carry mode, subject, and correlation explicitly instead of relying on transport defaults.
  • Keep denial outcomes machine-readable.

Common mistakes

  • Sending raw payloads without subject identity.
  • Making policy failures indistinguishable from execution failures.
  • Dropping correlation context before evidence is emitted.

Related concepts

Keep reading through the boundary.

Host →Invocation →Policy →