OpenHands Software Agent SDK: OpenHands V1 아래에 깔린 이벤트 소싱 기반, 로컬에서 원격까지의 토대
— 회 조회
코드 에이전트를 만들기 위한 깔끔하고 모듈화된 Python/REST SDK — OpenHands V1, CLI, OpenHands Cloud 뒤의 엔진이다. 이벤트 소싱 상태, 로컬 우선에 샌드박스는 온디맨드, MCP 도구. v1.26.0는 2026년 6월 5일 출시.
pip install -U openhands-sdk openhands-tools무엇인가
OpenHands Software Agent SDK는 코드를 다루는 에이전트를 만들기 위한 Python 및 REST API 모음이다. 이것은 OpenHands V1의 핵심으로 — 에이전트 코어를 그 위에 만들어진 앱들로부터 분리한 밑바닥부터의 재설계다(OpenHands CLI와 OpenHands Cloud 둘 다 이 SDK 위에서 돈다). 저장소는 MIT 라이선스이며 빠르게 움직인다. 최신 태그 v1.26.0는 2026년 6월 5일에 도착했고, v1.25.0(6월 4일)과 v1.24.0(5월 27일)에 바로 뒤이은 것이다.
핵심 주장은, 동일한 에이전트 정의가 프로토타이핑을 위해 노트북에서도, 프로덕션의 컨테이너화된 샌드박스 안에서도 코드 변경 거의 없이 돌아야 한다는 것이다. LLM, 타입이 지정된 Tool 목록, 그리고 워크스페이스에 묶인 Conversation을 구성한 다음, 메시지로 그것을 구동한다.
이 아키텍처가 흥미로운 이유
함께 나온 논문(arXiv 2511.03690, MLSys 2026 구두 발표이기도 하다)은 이 SDK를 전혀 채택하지 않더라도 훔쳐올 가치가 있는 네 가지 설계 원칙을 제시한다.
- 선택적 격리 — 로컬 우선, 샌드박스는 온디맨드. 정말로 격리가 필요할 때만 Docker/Kubernetes 비용을 치른다.
- 불변 설정과 이벤트 소싱 상태를 갖춘 무상태 컴포넌트. 이것이 한 번의 실행에 대한 결정론적 리플레이를 안겨준다.
- 에이전트 코어와 그것을 소비하는 애플리케이션 사이의 엄격한 분리.
- 네 개의 패키지 — SDK, Tools, Workspace, Server — 에 걸친 2계층 조합 가능성. 타입이 지정되고 교체 가능한 컴포넌트와 MCP 통합을 갖춘다.
이벤트 소싱에 불변 설정을 더한 것이 조용한 핵심이다. 모든 상태 전이가 덧붙여진 이벤트라면, 실패한 에이전트 실행을 결정론적으로 리플레이할 수 있다 — 로그에서 비결정론적 루프를 재현하려 애쓰는 대신에.
설치와 실행
pip install -U openhands-sdk openhands-tools문서는 openhands-sdk와 openhands-tools가 한 쌍의 세트임을 분명히 한다 — 하나의 명령으로 함께 설치하고 업그레이드해 버전을 맞춘 채로 유지하라. 샌드박스화된 워크스페이스와 동봉된 서버가 필요하면 openhands-workspace openhands-agent-server를 추가하라.
| 패키지 | 역할 |
|---|---|
| openhands-sdk | 핵심 agent/conversation/LLM API |
| openhands-tools | 내장 터미널, 파일 편집기, 작업 추적 도구 |
| openhands-workspace | Docker / 원격 샌드박스화 워크스페이스 |
| openhands-agent-server | REST/WebSocket 에이전트 서버 |
최소 실행은 터미널, 파일 편집기, 작업 추적기를 하나의 에이전트에 연결하고, 그것을 현재 디렉터리로 향하게 한 다음, 단일 지시를 보낸다 — 에이전트는 계획하고, 도구를 호출하고, 스스로 멈춘다.
실무자 메모
이 네 패키지로의 분할을 상용구가 아니라 실제 제품으로 다뤄라. 우선 openhands-sdk + openhands-tools만 로컬 워크스페이스에 대고 써서 그 루프를 느껴보고, 신뢰할 수 없는 편집을 격리해 실행해야 할 때가 되어서야 openhands-workspace에 손을 뻗어라. 도구는 타입이 지정되고 교체 가능하며 MCP를 지원하므로, 코어를 fork하지 않고도 자신의 도구를 끼워 넣을 수 있다 — 이것이 확장하는 대상으로서의 라이브러리와, 맞서 싸우는 상대로서의 하네스 사이의 차이다.
덜 고려된 각도
대부분의 「agent SDK」 보도는 그것이 어떤 모델을 호출하는지에 집착한다. 여기서 더 오래 가는 베팅은 이벤트 소싱 상태 모델이다. 결정론적 리플레이는 불안정한 에이전트 실행을, diff하고 감사하고 회귀 테스트할 수 있는 재현 가능한 산출물로 바꾼다. 이것은 에이전트를 채팅 세션에서, 빌드 파이프라인에 더 가까운 무언가로 재정의한다 — 그리고 그것이야말로 팀이 진짜 코드의 리팩터링을 맡겨 신뢰하기 전에 필요로 하는 것이다.