Live: get scene
live_get_sceneCapture a live frame as PNG plus structured scene data including selection, viewport, and visible objects for agent reasoning.
Instructions
Capture one live frame as a PNG PLUS a structured, machine-readable LiveScene.
When to use: the core perception step — the agent reasons over STRUCTURE, not pixels. For
pixels-only use live_render_view; for one loop iteration use live_session_step.
Key params: region/scale/fast work exactly as live_render_view (all four region parts at once,
user units, w/h > 0; optional scale > 0; fast=True for the downscaled loop preview, explicit
scale wins). Frame rendered through the transport, never an OS screenshot
(deterministic, cross-platform — ADR-006); served from the per-session cache keyed on
(doc_revision, viewport, scale). Scene pulled over the fixed get_scene command — no
code or raw Action path (ADR-003). Requires an established session. READ-ONLY (no Operation
Record, no approval).
Return shape: LiveSceneFrame — render (the PNG) plus scene: a LiveScene carrying the
active-document identity, selection (ids + bboxes), viewport (zoom/center/visible region), the
canvas size, and a visible-object summary.
Example: live_get_scene(fast=True)
Risk class: low (read-only perception; no document mutation, no Operation Record).
Input Schema
| Name | Required | Description | Default |
|---|---|---|---|
| fast | No | ||
| scale | No | ||
| region_x | No | ||
| region_y | No | ||
| region_width | No | ||
| region_height | No |
Output Schema
| Name | Required | Description | Default |
|---|---|---|---|
| scene | Yes | Structured scene paired with this frame (read-only). | |
| render | Yes | Rendered frame (workspace-relative PNG path). |