Skip to main content
The spatial protocol separates intent from rendering. An agent requests a semantic action; the shell resolves that action into its model, animations, voice, and scene.

​
Canonical Entity path

The browser connects to the spatial gateway over WebSocket. The ngram_entity binding connects that gateway to the Python Entity bridge. Keep those two connections distinct when diagnosing a failed session.

​
Message envelope

Protocol messages include a type, Unix-millisecond timestamp, and sessionId. For example:
Session identifiers correlate actions with a live surface. They are not the Entity’s persistent identity or a canonical person identifier.

​
Tool schema and wire schema are different

The Python tool uses ar_spawn_object and snake-case parameters such as object_id. The protocol action uses action:spawn_object and objectId. The adapter performs that translation. The TypeScript protocol defines more message types than the canonical Entity’s 21 spatial tools. A type existing in protocol.ts does not mean a matching agent tool is registered, or that every surface implements it.

​
Streaming and cancellation

The bridge can deliver activity, speech, and spatial actions during a turn. The surface’s event:cancel_turn and recognized direct stop speech cancel active spatial work. A queued action is a delivery attempt; verify important visible outcomes in the surface. Cancellation applies to active work. It does not undo an already completed external tool action or shut down the Entity worker.

​
Extension points

Use the shipped interfaces as the basis for a custom binding: These paths refer to the application repository, not the documentation checkout. Keep identity ownership, person mapping, authentication, capability reporting, cancellation, and reconnect behavior explicit in a new adapter.