Skip to main content
An agent should know what its environment exposes before claiming what it can perceive or do. The first tool for that is ar_inspect_surface.
The result includes spatial tool names and the connected surface’s context. A connected body can be inspected from another conversation with the same Entity. It describes a live interface, not files inside the Entity’s execution workspace.

​
Three different kinds of evidence

​
Desktop and immersive AR

The runtime’s advertised support and a user’s permission to start playback or capture are separate conditions.

​
Capture is not unrestricted vision

ar_request_capture returns rendered virtual-scene images through a correlated tool receipt. With view sharing enabled, agents can inspect the current view or use an independent camera for named angles, close-ups, isolation, and diagnostic lighting. The desktop camera button and XR menu control the same permission; Share view sends a single user-requested image. See Vision. These images exclude physical webcam pixels and headset passthrough. The surface explicitly reports physicalCamera: false. XR current-view capture uses the headset eye pose, but headset hardware behavior still requires verification on the target device. Handle capture failure or missing visual input explicitly. Do not infer hand positions, gaze, or objects in a real room from desktop mode alone.

​
Optional services

For creations, use ar_world capabilities for the runtime contract and ar_world observe for actual object bounds, transforms, ownership, asset status, program errors, and performance. ar_blender capabilities separately checks Blender on the execution host. A successful Blender export and a ready Spatial asset are separate results. The current world supports custom geometry, physics, instancing, scoped programs, controls, and Blender previews. It does not claim physical room mesh understanding or shared cloud world synchronization. See Creations for persistence and desktop/XR interaction boundaries. For skies and scene lighting, use ar_environment capabilities for the contract and inspect for the applied configuration, loading errors, and effective visibility and reflections. A configured sky can be hidden while it still lights materials. XR preserves passthrough by default; immersive sky display must be enabled explicitly. Environments explains authored panoramas and the matching human controls. Generated motion needs an external motion backend. The AR gateway reads NGRAM_AR_MOTION_PROVIDER_URL and optional token/timeout variables. The adapter calls /v1/motion and expects a compatible generated clip. Browser pages can refuse embedding. Media playback can require a user gesture or be unavailable for a particular video. A registered ar_open_browser or ar_play_youtube tool cannot override those conditions.

​
A useful inspection habit

Inspect once when entering a session or when a capability changes. Use the returned evidence to act. Repeating a registry inventory is not progress on the user’s request; if an action fails, inspect that specific failure and report the limitation.