Trabaja con dispositivos en código

Cuando un dispositivo se adjunta a un hilo, se proyecta en un árbol .commandagi/, agrupado por qué tipo de cosa es. Los archivos están vivos: leer uno te da los datos más recientes, sin ceremonia de sondeo.

.commandagi/
  computers/<id>/
    screen.mjpeg                  # the screen AS VIDEO — Motion JPEG, its frames concatenated
    screen.latest.jpg             # the latest screen frame
    screen.structure.jsonl        # the UI accessibility tree, as a log
    display.jsonl                 # WRITE here to draw on the screen
    details.json                  # what this embodiment is: model, capabilities, location
  cameras/<id>/
    camera.mjpeg                  # the camera as video
    camera.latest.jpg             # latest camera frame
  robots/<id>/
    camera.mjpeg   pose.jsonl   joints.jsonl   force.jsonl

El archivo de un stream es lo que SON sus bytes, y la regla es la misma para cada tipo de dispositivo:

• Una pantalla o una cámara es un stream de vídeo, así que su archivo es <stream>.mjpeg — Motion JPEG, que ffmpeg y VLC abren. Donde un script de captura lo produce, <stream>.latest.jpg queda a su lado como este fotograma.
• Un stream estructurado — pose.jsonl, el árbol de interfaz — es un log de solo anexado con el stream completo acumulado. Síguelo como cualquier log para ver cada actualización, o lee .latest.json para el valor actual.

Aquí no se inventa nada: un stream de vídeo es un archivo de vídeo y un stream de eventos es un log, así que ffmpeg, tail -f y jq funcionan sin cambios.

Los mismos datos, elige la superficie que se ajuste a tu código.

1. El SDK — el camino rápido para un ciclo.

from commandagi import CommandAGI

cagi = CommandAGI(api_key="cagi_…")
with cagi.launch("computer/software-engineer") as pc:
    frame = pc.observe()                       # bytes of the latest screen frame
    pc.step("click", x=640, y=400)             # drive it
    pc.step("type", text="hello")

2. Como archivos — monta tu espacio de trabajo por WebDAV.

Tu Drive (que incluye el árbol .commandagi/) se monta por WebDAV, así que cualquier herramienta que lea archivos funciona — shell, rclone, la API de archivos de tu lenguaje. Ideal para scripting y pegamento.

# mount your workspace over WebDAV, then it's just files
cat     .commandagi/computers/<id>/screen.latest.jpg    # latest screen frame (image bytes)
ffmpeg -i .commandagi/computers/<id>/screen.mjpeg out.mp4   # the screen, as video
tail -f .commandagi/robots/<id>/pose.jsonl              # follow a robot's pose, live
jq .    .commandagi/computers/<id>/screen.structure.latest.json   # the current UI tree

3. El cable en tiempo real — push, para baja latencia.

// realtime: wss://api.commandagi.com/rt/thread/{threadId}?role=owner&token={cagi_key}
← { "t": "frame", "embodimentId": "…", "channelId": "screen",
    "url": "data:image/png;base64,…" }                          // frames stream in
→ { "t": "control", "embodimentId": "…", "action": "type", "payload": { "text": "hello" } }

Un solo vocabulario de acciones se mapea a lo que sea que el dispositivo pueda hacer físicamente — una laptop, una VM en la nube, un teléfono, un robot. Envía acciones por el SDK (step/act) o el WebSocket (control).

• Computadora / teléfono: click, double_click, right_click, move, drag, scroll, type, key (el espacio de coordenadas es 1280×800).
• Robot / simulación: move, back, turn, stop, reset, joint, pose, gripper.

Una computadora o teléfono también expone un archivo escribible, display.jsonl. Donde los otros archivos son cosas que lees, este lo escribes — cada línea es una operación que dibuja en el dispositivo: superpone una pista en la UI en vivo, presenta una escena HTML/pizarra, o habla. Es cómo un agente muestra su trabajo o saluda a una persona.

# a computer/phone screen is a WRITABLE file — write an op, it draws
echo '{ "op": "say", "text": "Hi — I can help with that." }'                 >> display.jsonl
echo '{ "op": "scene", "scene": { "kind": "html", "html": "<h1>Welcome</h1>" } }' >> display.jsonl

El patrón sigue: los propios puertos de una máquina (un dispositivo serial, un periférico USB, un puerto TCP local) aparecen bajo dev/ como archivos de lectura/escritura, y el details.json de cada dispositivo te dice qué es y dónde se ubica físicamente. El acceso a cualquiera de ellos es un permiso otorgado sobre el archivo — nada a la medida.