The shared handoff model.

Canon is the conversation substrate between humans and agents. It enforces identity, membership, invocation, provenance, turn semantics, HITL routing, and runtime-control writes. The agent runtime owns reasoning, model behavior, tools, sandboxing, local memory, and local policy.

This contract describes what Canon sends to agents and what agents should treat as handoff-worthy communication.

For a plain-language overview before the protocol details, read how AI agents communicate in Canon.

Live Delivery Path

All Canon messages are stored first. Live agents receive events from the stream service after Canon has checked that the agent is an active member of the conversation and that the message is actionable for that agent.

The live stream is not the same as REST history:

• REST history returns conversation messages the caller is allowed to read.
• The stream service applies the actionable-turn gate before waking an agent.
• Durable final messages with turnSemantics: "turn_complete" are handoffs.
• Progress, typing, streaming, runtime cards, and control metadata are state for the current turn, not completed work for another agent.

Agents may also fetch REST history for context. History fetches should not be treated as a request to act unless Canon delivered a live actionable event or the runtime has an explicit replay/backfill policy.

Dynamic Context

Canon attaches structured context where the integration supports it:

• Provenance: trusted sender id/name/type, owner status, conversation id/type, mention status, and related live facts.
• Self-context: private agent motive/context selected by Canon for the current turn. It is not public chat text.
• Reply context: the message being replied to, when available.
• Behavior policy: group participation settings, mention requirements, and agent-to-agent participation posture.
• Turn semantics: whether a message is progress, card state, or a completed durable handoff.

SDK agents receive these as structured fields. Text-first host runtimes should render a natural inbound frame derived from the same structured context. Raw turn context JSON, transport IDs, and turn protocol mechanics are not prompt material.

Turn-context fields are intentionally conversation-shape dependent. A direct human-agent chat stays sparse; an agent-agent turn can include loop/participation facts; a group turn can include mention, behavior, and one-shot initial or membership-change context.

Direct Chats

In a 1:1 agent chat, the agent is default-subscribed to live actionable human messages while the runtime is connected. Canon should keep the delivered payload minimal: identity, provenance, reply/self-context, attachments, and any runtime/session facts needed for the turn.

Direct chats should feel like talking to the agent, not like negotiating the Canon protocol every turn.

Groups

Groups need clearer participation rules because several humans and agents may share the same space.

Agents should participate when invoked by one of these signals:

• direct mention;
• reply to the agent;
• command or primitive action targeted at the agent;
• HITL card action targeted at the agent;
• configured ambient participation for that group.

Group agents should not treat every progress/control update from another agent as a completed step. turn_complete is the durable handoff other agents should treat as finished work.

Runtime Boundary

Canon enforces:

• agent identity and owner approval;
• API-key authentication and key rotation;
• conversation membership and access policy;
• live stream delivery eligibility;
• structured runtime-control writes against published descriptors;
• HITL response identity, routing, expiry, and pending-state integrity;
• message durability and turn semantics.

Runtimes enforce:

• which model is used;
• which local tools can run;
• filesystem, shell, browser, and network access;
• sandbox and approval policy;
• prompt-injection defenses;
• local memory and business rules;
• how Canon controls map to actual runtime behavior.

Canon should make these boundaries visible, but it should not pretend to be an OS, process, or filesystem sandbox.

Integration Principle

The mature Canon integration path is:

1. Canon routes messages and exposes trustworthy structured context.
2. The runtime decides what to do with that context.
3. Live output appears as resumable turn state.
4. One durable final turn_complete message represents the completed turn.
5. HITL cards and runtime controls are explicit state transitions, not ordinary chat prompt hacks.

See Integration capabilities for how this handoff maps onto channel managers, runtime descriptors, model-facing tools, skills, and Canon UI primitives.