机器人与仿真
在真实的 3D 世界中测试机器人
从代码中启动一个云端 3D 物理仿真（或一个真实的机器人单元）——传输机器人的摄像头画面，发送驾驶动作，并重置回合。没有智能体：由你来驾驶它，就像一个云端健身房。
Python SDK
最快的路径。launch() 会配置一台真实的 GCE 虚拟机来运行这个 3D 世界，等待它开始传输，并交给你一个可以观察和操作的 World。始终用 close()（或使用 with 代码块）来关闭它，以释放这台虚拟机。
pip install commandagifrom commandagi import CommandAGI
cagi = CommandAGI(api_key="cagi_…") # or set COMMANDAGI_API_KEY
# Launch a real 3D physics world with a mobile robot and drive it yourself.
with cagi.launch("simulation/warehouse") as world:
obs = world.observe() # JPEG bytes from the robot's head camera
for _ in range(20):
obs = world.step("turn", dir="left") # send an action, get the next frame
world.reset() # robot back to the episode start
# leaving the block stops the world and releases the cloud VM同时也提供 Node/TypeScript（npm install commandagi）和 Go（早期版本）版本。也可以从任何语言直接使用底层的 HTTP + WebSocket API（见下文）。
你可以启动的世界
内置的 3D 仿真会把一台移动机器人放进一个带头部摄像头和可驾驶底盘的物理场景中：
simulation/warehouse——一个需要在货架和托盘之间导航的场景。simulation/arm-cell——一个用于操作的桌面机械臂 + 夹爪。simulation/playground——一个带有可驾驶巡视车的开放世界。simulation/the-matrix——共享的公开世界（免费）。
计算机的工作方式相同——cagi.launch("computer/software-engineer") 会给你一台实时的 Ubuntu 桌面，它的 observe() 返回屏幕画面，它的动作是 click/type/key。
控制词汇
动作通过 world.act(name, **payload) 或 world.step(name, **payload) 发送：
- 机器人 / 仿真：
move(speed)、back(speed)、turn(dir, rate)、stop、reset（新回合——机器人回到起始姿态）。 - 计算机：
click(x, y)、type(text)、key(key)、move(x, y)、scroll(x, y, dy)（坐标空间为 1280×800）。
不使用 SDK——原始 HTTP + WebSocket
一台「机器」就是一个带有一台设备、没有智能体的会话。创建它，接入一个世界，然后打开实时通道来传输画面帧并发送动作。这正是 SDK 所封装的内容。
# 1. Create an agentless machine, then attach a simulation world.
SID=$(curl -s https://api.commandagi.com/embodiment-threads \
-H "Authorization: Bearer $COMMANDAGI_API_KEY" -d '{}' | jq -r .threadId)
curl -s https://api.commandagi.com/threads/$SID/robots \
-H "Authorization: Bearer $COMMANDAGI_API_KEY" \
-d '{ "snapshotId": "simulation/warehouse" }'
# → { "status": "granted", "worldId": "…", "embodimentId": "…" }
# Poll GET /threads/$SID until the embodiment status is "live" (~60–90s).// wss://api.commandagi.com/rt/thread/{threadId}?role=owner&token={cagi_key}
// Control requires &token=<your API key> and you must own the thread. All messages are JSON.
← { "t": "frame", "embodimentId": "…", "channelId": "cam-head",
"url": "data:image/jpeg;base64,…" } // the robot's head camera
→ { "t": "control", "embodimentId": "…", "action": "move", "payload": { "speed": 0.8 } }/embodiment-threads创建一台无智能体的机器（一个由你驾驶、没有智能体的会话）。/app/threads/:id/robots接入一个 3D 仿真或一台物理机器人。/app/threads/:id/computers接入一台云端计算机。/me/embodiment-threads你正在运行的机器。/app/threads/:id/exec暂停这个会话（它的闲置保活会释放该虚拟机）。自带机器人
另一个方向：把你的机器人接入平台。register_robot() 会创建一台设备并返回一座桥——发布你机器人的摄像头画面，并应用它收到的动作。任何拥有该会话的人（一个人、一个智能体，或另一位开发者的 World 客户端）就都可以观看并驾驶你的机器人，就像一个托管的仿真一样。
from commandagi import CommandAGI
cagi = CommandAGI(api_key="cagi_…")
bridge = cagi.register_robot("my-rover") # registers a robot embodiment on the platform
print("watch + drive it at:", bridge.thread_url)
bridge.run(
camera=lambda: my_robot.jpeg_frame(), # () -> JPEG/PNG bytes (your camera)
on_action=lambda a, p: my_robot.do(a, p), # apply incoming actions to your hardware
fps=10,
) # blocks; Ctrl-C to take the robot offline一个完整的、无需硬件的示例（一台今天就能运行的虚拟巡视车，之后可以换成真实硬件）：github.com/CommandAGI/commandagi-example-byo-robot。在底层，这就是同一套实时协议的反向使用——你的桥会发送 frame 消息并接收 control 消息。
快照与分叉
捕获一个世界的状态，以便之后分叉（从那个确切的时间点得到一台全新的虚拟机）：POST /threads/:id/devices/:deviceId/snapshot。通过在接入调用中传入 fromSnapshotId，从一份快照启动。闲置的世界也会在保活窗口结束后自动拍摄快照并关闭。