Strands Agents와 LeRobot을 통해 Hugging Face Hub에서 로봇 하드웨어로

Strands Robots의 LeRobot 통합 과정 안내 - Hub 데이터셋에서 물리적 로봇에 이르기까지, 동일한 디스크 포맷의 sim-to-real 데이터셋과 문자열 하나로 교체 가능한 정책(policy)을 사용하는 단일 에이전트 루프.

로봇이 있고, Hugging Face Hub에 데모 데이터 폴더가 있으며, 로봇이 배우길 원하는 새로운 작업이 있다고 가정해 봅시다. 오늘날 이를 수행하려면 다섯 가지의 별도 도구가 필요합니다. 새로운 데모를 기록하기 위한 도구 하나, 학습을 위한 도구 하나, 시뮬레이션에서 테스트하기 위한 도구 하나, 하드웨어에 배포하기 위한 커스텀 코드, 그리고 로봇이 한 대 이상일 때 이를 조정하기 위한 또 다른 도구가 필요합니다. 각 요소는 개별적으로 작동하지만, 서로 소통하지는 않습니다.

Strands Robots는 AWS에서 제공하는 오픈 소스 SDK(Apache 2.0)로, 로봇 추상화(robot abstractions), 시뮬레이션, 그리고 LeRobot 스택을 단일 Strands 에이전트로 구성할 수 있는 AgentTools로 노출합니다. 이 통합은 의도적으로 얇게(thin) 설계되었습니다. LeRobot 자체 스크립트가 하드웨어 기록 및 캘리브레이션(calibration)을 처리하며, Strands AgentTools는 에이전트가 실제로 오케스트레이션(orchestrate)하는 부분에 투입됩니다. 시뮬레이션 도구는 LeRobot이 하드웨어에서 작성하는 것과 동일한 형식으로 LeRobotDatasets를 기록합니다. GR00T와 LerobotLocal은 공통 인터페이스 뒤에서 정책 추론(policy inference)을 수행하며, MolmoAct2 체크포인트는 LerobotLocal 경로를 통해 실행됩니다. 피어 메쉬(peer mesh)는 에이전트를 원격 로봇으로 확장합니다. 데이터셋 형식은 LeRobot이 작성한 그대로 유지되며, 에이전트 루프가 그 접착제 역할을 합니다.

이 포스트에서는 단일 에이전트 내부의 다섯 단계를 안내합니다: LeRobot AgentTools를 기반으로 에이전트 구축하기, 시뮬레이션에서 LeRobotDataset으로 데모 기록하기, 동일한 로봇에서 정책 실행하기, 키워드 인자(keyword argument) 하나만 변경하여 동일한 에이전트 코드를 물리적인 SO-101에 배포하기, 그리고 Zenoh 메쉬를 통해 함대(fleet) 전체에 명령을 방송하기입니다. 마지막에는 GitHub에서 작동하는 샘플 애플리케이션을 클론하여 노트북의 시뮬레이션에서 실행해 볼 수 있습니다. 기본 경로를 사용하는 데 하드웨어, GPU, Hugging Face 자격 증명이 필요하지 않습니다. 이 포스트의 실행 가능한 동반 파일은 examples/lerobot/hub_to_hardware.py 및 hub_to_hardware.ipynb에 있습니다.

해당 노트북은 기본적으로 시뮬레이션 전용(sim-only)이며 Mock-policy를 사용합니다.

Strands Robots SDK는 LeRobot 스택을 하나의 Strands 에이전트(agent)로 구성할 수 있는 에이전트 도구(AgentTools)로 노출합니다. 이 포스트의 예시 에이전트는 네 가지 작업을 수행합니다: 시뮬레이션에서 새로운 시연(demonstrations)을 기록하고, 그 결과를 LeRobotDataset으로서 Hub로 푸시하며, 동일한 포맷을 사용하여 시뮬레이션에서 정책(policy)을 실행하고, 단 하나의 키워드 인자(keyword argument) 변경만으로 동일한 에이전트 코드를 실제 로봇에 배포합니다. 로봇이 한 대 이상일 경우, 에이전트는 내장된 피어 메시(peer mesh)를 통해 전체 플릿(fleet)을 조정할 수 있습니다. 하드웨어 기록 및 보정(calibration)의 경우, LeRobot 자체 CLI(lerobot-record, lerobot-calibrate)가 초기 설정(bring-up)을 처리하며, 에이전트는 그 이후 단계부터 작업을 이어받습니다.

그림 1. Robot("so100")은 기본적으로 MuJoCo 기반 시뮬레이션을 반환하며, mode="real"은 LeRobot에 의해 구동되는 하드웨어 로봇을 반환합니다. 두 모드는 동일한 DatasetRecorder와 동일한 정책 제공자(policy providers)를 공유하므로, 시뮬레이션에서 캡처된 데이터셋과 하드웨어에서 캡처된 데이터셋은 동일한 디스크 기반 LeRobotDataset 포맷을 사용합니다.

이러한 작동을 가능하게 하는 두 가지 설계 선택이 있습니다. 첫째, Robot("so100")은 기본적으로 시뮬레이션을 반환하여(하드웨어 불필요, 위험 없음), mode="real"은 LeRobot에 의해 구동되는 하드웨어 기반 로봇을 반환합니다. 에이전트 코드는 두 모드 모두에서 동일합니다. 둘째, LeRobotDataset을 작성하는 DatasetRecorder가 시뮬레이션 경로와 LeRobot 자체의 하드웨어 기록 간에 공유되므로, MuJoCo에서 캡처된 데이터셋과 실제 SO-101에서 캡처된 데이터셋은 동일한 포맷을 갖게 됩니다.

다섯 줄의 Python 코드로 구현된 전체 워크플로:

from strands_robots import Robot
from strands import Agent
arm = Robot("so100") # mode="sim" (기본값 - 안전함, 하드웨어 불필요)
...

다음은 해당 호출 내부에서 실제로 단계별로 일어나는 과정입니다.

• Linux 또는 macOS(MuJoCo 백엔드의 경우 Apple Silicon 지원) 환경의 Python 3.12+.
• 에이전트의 추론(reasoning)을 위한 Strands 호환 모델 제공자(Model Provider). AWS 자격 증명이 포함된 Amazon Bedrock, Anthropic API, OpenAI, 또는 로컬에서 실행되는 Ollama.
• 다음의 추가 설치 항목(install extras)과 함께 설치된 Strands Robots:
  uv pip install "strands-robots[sim-mujoco,lerobot,mesh]"

끝입니다. 이 포스트의 예제는 이 세 가지가 갖춰진 노트북에서 엔드 투 엔드(end-to-end)로 실행됩니다.

• Hub에서 데이터셋을 푸시(push)하고 정책 체크포인트(policy checkpoints)를 풀(pull)하기 위한 쓰기 권한이 있는 Hugging Face 계정 및 토큰.
• 하드웨어 경로의 경우: SO-101 팔로워(follower) 및 리더(leader) 쌍, 또는 LeRobot이 지원하는 다른 로봇. 두 장치 모두 ~/.cache/huggingface/lerobot/calibration/ 아래에 교정(calibration) 파일이 필요합니다.
• 로컬 GR00T 추론(inference)의 경우: 최소 16GB의 비디오 메모리를 갖춘 NVIDIA GPU 및 설치된 Docker. 이 포스트는 gr00t_inference 도구의 lifecycle="full" 액션을 사용하며, 이는 한 번의 호출로 이미지를 가져오고, 체크포인트를 다운로드하며, 컨테이너를 시작합니다.

Strands Robots를 설치하고 예제 파일을 가져오세요:

uv pip install "strands-robots[sim-mujoco,lerobot,mesh]"
git clone https://github.com/strands-labs/robots.git
cd robots

에이전트가 Hub에서 데이터셋을 푸시하거나 정책을 풀기를 원한다면 Hugging Face 토큰을 내보내기(export) 하세요. 이 포스트의 기본 시뮬레이션 경로에서는 선택 사항입니다. 예제는 Mock 정책을 사용하여 엔드 투 엔드로 실행되며, Hub 접근 권한 없이도 데이터셋을 로컬 캐시에 기록합니다.

export HF_TOKEN=hf_...

실행 가능한 예제는 strands-labs/robots 리포지토리 내의 MuJoCo 및 LIBERO 예제와 함께 examples/lerobot/hub_to_hardware.py (Python 스크립트) 및 hub_to_hardware.ipynb (노트북)에 위치합니다. 노트북을 시작점으로 권장합니다. JupyterLab에서 노트북을 열고 하드웨어를 연결하지 않은 상태로 시뮬레이션 모드에서 셀을 위에서 아래로 실행하세요.

시뮬레이션 도구는 LeRobot이 하드웨어에서 기록하는 것과 동일한 형식으로 LeRobotDatasets를 기록합니다. 하드웨어는 필요하지 않습니다. Simulation

도구의 start_recording 액션은 동일한 DatasetRecorder를 통해 기록합니다:

클래스: 관절 상태(joint states)와 액션(actions)을 위한 동일한 parquet 스키마, 카메라별 동일한 MP4 레이아웃을 사용합니다. 에이전트 프롬프트도 거의 동일합니다:

from strands import Agent
from strands_robots import Robot
robot = Robot("so100") # 기본값은 mode="sim"
...

Figure 2. MuJoCo 시뮬레이션에서의 기록 장면: 바닥면에 있는 빨간색 큐브를 향해 뻗는 SO-100 로봇 팔이 LeRobotDataset으로 캡처되었습니다. 이 기본 경로에서는 하드웨어, GPU, Hugging Face 인증 정보가 필요하지 않습니다.

Mock 정책은 의도된 것입니다. 이는 훈련된 체크포인트(checkpoint) 없이도 워크플로우가 엔드 투 엔드(end-to-end)로 실행될 수 있도록 자리 표시용 관절 액션(joint actions)을 생성합니다. 로봇은 움켜쥐기(grasp)를 완료하는 대신 무작위 동작을 수행하며, 기록은 구조적으로 완전하지만(유효한 관절 상태, 유효한 카메라 프레임, 잘 형성된 LeRobotDataset 에피소드), 데모 자체는 훈련 데이터로서 유용하지 않습니다. 아래의 3단계에서는 실제 움켜쥐기 동작을 위해 GR00T 또는 LerobotLocal로 교체합니다. 이 단계에서 실제 큐브를 집는 모습을 보려면 --policy lerobot_local --checkpoint allenai/MolmoAct2-SO100_101을 실행하세요.

(config.json에서 자동 감지되어 LerobotLocal 경로를 통해 라우팅된 MolmoAct2 체크포인트임); 프롬프트, 데이터셋 형식, 에이전트 코드는 동일하게 유지됩니다.

증거는 그다음에 일어나는 일입니다. LeRobot 자체의 데이터셋 로더(dataset loader)는 Strands 전용 코드 경로 없이 시뮬레이션에서 기록된 데이터를 읽습니다:

from lerobot.datasets.lerobot_dataset import LeRobotDataset
dataset = LeRobotDataset("my_user/cube_picking_sim")
print(dataset.features)
...

이 features 딕셔너리는 Hub에 있는 다른 모든 LeRobot 데이터셋과 형태가 동일합니다: 동일한 컬럼 이름, 동일한 parquet+MP4 레이아웃, 동일한 로더 경로를 가집니다. 하드웨어에서 기록된 데이터를 사용하는 훈련 스크립트는 수정 없이 시뮬레이션에서 기록된 데이터를 그대로 사용할 수 있습니다. 시뮬레이션에서 푸시(push)된 데이터셋은 원하는 경우 동일한 Hub 저장소(repository) 내에서 하드웨어 기록 데이터와 나란히 존재할 수 있습니다.

기록된 LeRobotDataset의 단일 에피소드로, 레코더가 작성한 카메라별 MP4 파일로부터 재생되며, 이는 학습 스크립트가 읽어들이는 것과 동일한 디스크 상의 비디오입니다.

시뮬레이션 대신 실제 SO-101 하드웨어에서 시연(demonstration)을 기록하려면, LeRobot의 record CLI를 직접 사용하십시오. Strands 통합은 해당 명령을 AgentTool로 래핑(wrap)하지 않는데, 이는 LeRobot이 이미 해당 작업을 깔끔하게 수행하기 때문입니다:

lerobot-calibrate --robot.type=so101_follower --robot.id=my_follower
lerobot-calibrate --robot.type=so101_leader --robot.id=my_leader
lerobot-record \
...

이 명령을 통해 Hub에 업로드되는 데이터셋은 시뮬레이션 기록과 동일한 형식입니다. 이를 통해 정책(policy)을 미세 조정(fine-tune)하려면 LeRobot의 training CLI(lerobot-train)를 실행하십시오. 학습 자체는 이 포스트의 범위를 벗어나며 표준 LeRobot 워크플로우를 따릅니다. 단계 3부터 에이전트는 원본 체크포인트 또는 미세 조정된 체크포인트를 교체하며 사용합니다. 전체 SO-101 하드웨어 설정, 보정(calibration) 가이드 및 문제 해결에 대해서는 예제 폴더의 README를 참조하십시오.

Hub에 데이터셋이 준비되면 다음 단계는 정책을 실행하는 것입니다. 예제에서는 기본 시뮬레이션 모드인 Robot() 팩토리(factory)를 사용한 다음, gr00t_inference를 연결하여 에이전트가 추론(inference) 컨테이너를 관리할 수 있도록 합니다:

from strands import Agent
from strands_robots import Robot, gr00t_inference
robot = Robot("so100") # 기본값은 mode="sim"
...

내부적으로 에이전트는 gr0루트_inference(action="lifecycle", lifecycle="full", ...)를 실행하여 GR00T 컨테이너 이미지를 가져오고, Hub에서 체크포인트를 다운로드하며, 추론 서비스를 시작합니다. 그런 다음 policy_provider="groot"와 함께 시뮬레이션된 로봇에 대해 run_policy 액션을 실행하며, 이때 policy_config 딕셔너리에 GR00T 서비스의 호스트와 포트를 전달합니다 (컨테이너는 5555 포트로 접속 가능합니다). 시뮬레이션은 정책의 액션 청크(action chunks)와 함께 진행되며, 결과 렌더링은 Simulation.render를 통해 확인할 수 있습니다.

Figure 3. 훈련된 정책(a GR00T 또는 MolmoAct2 체크포인트)을 사용하여, 에이전트가 시뮬레이션 내에서 빨간색 큐브를 잡기 위해 SO-100을 구동하며, 이는 Mock 정책이 대신 수행하는 동작입니다.

프로세스 내 추론(in-process inference, 컨테이너나 ZeroMQ (ZMQ) 미사용)을 선호하는 개발자의 경우, gr00t_inference를 Hub 리포지토리에서 로드된 LerobotLocalPolicy 인스턴스로 교체하십시오. 프로바이더(provider)는 lerobot/ 조직 아래의 모든 모델 ID를 프로세스 내 경로로 라우팅합니다:

from strands_robots.policies import create_policy
policy = create_policy("lerobot/act_aloha_sim_transfer_cube_human")

LerobotLocalPolicy는 ACT, Diffusion Policy, SmolVLA, π0, 그리고 π0.5를 지원하며, LeRobot 자체의 정책 레지스트리(policy registry)가 config.json으로부터 해결할 수 있는 모든 것을 지원합니다. rtc_config를 포함하는 플로우 매칭(flow-matching) 정책(π0, SmolVLA)의 경우 실시간 청킹(Real-Time Chunking)이 자동으로 활성화됩니다.

NVIDIA가 최근 출시한 Cosmos 3 또한 동일한 인터페이스 뒤에서 정책 프로바이더(policy provider)로 사용할 수 있으므로, 어떤 프로바이더를 지정하더라도 에이전트 코드는 동일하게 유지됩니다.

참고: LerobotLocalPolicy는 trust_remote_code=True 옵션으로 Hugging Face 모델을 로드합니다. 이를 사용하려면 STRANDS_TRUST_REMOTE_CODE=1을 설정해야 하며, 신뢰할 수 있는 조직의 체크포인트만 로드하십시오.

이것은 키워드 인자(keyword argument) 하나만 변경된 Step 3와 동일한 코드입니다. Robot 팩토리(factory)는 LeRobot의 make_robot_from_config를 통해 구동되는 하드웨어 기반 로봇을 반환합니다:

robot = Robot(
"so100",
mode="real",
...

이제 동일한 에이전트 프롬프트가 실제 물리적 암(arm)에서 실행됩니다. 하드웨어 경로는 관절 명령(joint commands)과 카메라 읽기를 위해 LeRobot의 로봇 추상화(robot abstraction)를 사용하며, 5555 포트에서 접근 가능한 GR00T 컨테이너가 액션 청크(action chunks)를 생성합니다.

이것을 SO-101에서 실행하기 전에, 팔로워(follower)와 리더(leader) 모두에 대한 캘리브레이션(calibration)이 완료되어 있어야 합니다. LeRobot의 캘리브레이션 명령(lerobot-calibrate)을 실행하십시오.

) 장치당 한 번 수행하십시오. 파일은 ~/.cache/huggingface/lerobot/calibration/ 경로에 저장되며, 하드웨어에 접근하는 모든 Strands 코드 경로는 해당 위치에서 파일을 읽어옵니다. 캘리브레이션(calibration) 파일이 누락된 경우, 에이전트(agent)는 LeRobot 드라이버 레이어(driver layer)에서 발생하는 오류를 표시합니다.

지금까지는 한 번에 하나의 로봇만을 구동했습니다. 메쉬(mesh)는 Strands Robots가 하나 이상의 로봇을 처리하는 방식입니다. 책상 위의 리더 암(leader arm)이 다른 방에 있는 팔로워 암(follower arm)을 원격 제어(teleoperating)하거나, 다섯 대의 SO-101이 동일한 창고 작업을 병렬로 수행하거나, 휴머노이드(humanoid)가 모바일 베이스(mobile base)와 협업하는 모습을 상상해 보십시오. 이 모든 것이 메쉬 패턴(mesh patterns)입니다. 메쉬는 오픈 소스 피어 투 피어(peer-to-peer) 프로토콜인 Zenoh를 기반으로 구축되었으며, IP 주소를 관리하거나, 디스커버리(discovery) 코드를 작성하거나, 브로커(broker)를 선택할 필요가 없습니다. 새로운 로봇이 가동되는 즉시 메쉬에 나타나며, 에이전트는 이들 모두와 동시에 통신할 수 있습니다.

모든 Robot()

및 모든 Simulation()

은 자동으로 Zenoh 피어 메쉬(peer mesh)에 참여합니다. robot_mesh

도구는 에이전트에게 디스커버리(discovery), 구조화된 명령(structured commands), 브로드캐스트(broadcasts), 비상 정지(emergency stop)와 같은 플릿 운영(fleet operations)을 위한 어휘를 제공합니다:

agent = Agent(tools=[robot_mesh])
agent(
"List every robot and simulation on the mesh. "
...

에이전트는 robot_mesh(action="peers")를 호출합니다.