The OpenHands Software Agent SDK: A Composable and Extensible Foundation for Production Agents
이 논문은 소프트웨어 개발 에이전트의 유연한 구현, 안전한 실행, 그리고 인간과의 원활한 상호작용을 가능하게 하는 오픈핸즈 (OpenHands) 소프트웨어 에이전트 SDK 를 소개하고, 이를 통해 프로토타이핑부터 대규모 배포까지 에이전트 개발의 실용적인 기반을 마련했다고 주장합니다.
원저자:Xingyao Wang, Simon Rosenberg, Juan Michelini, Calvin Smith, Hoang Tran, Engel Nyst, Rohit Malhotra, Xuhui Zhou, Valerie Chen, Robert Brennan, Graham Neubig
원저자: Xingyao Wang, Simon Rosenberg, Juan Michelini, Calvin Smith, Hoang Tran, Engel Nyst, Rohit Malhotra, Xuhui Zhou, Valerie Chen, Robert Brennan, Graham Neubig
과거의 오픈핸즈 (V0 버전) 는 마치 모든 공구가 한 개의 거대한 통에 섞여 있는 '만능 공구함' 같았습니다.
문제점: 작은 나사 (간단한 기능) 를 찾으려면 거대한 통을 뒤져야 했고, 통이 깨지면 모든 공구가 고장 났습니다.
현실: 집 안 (내 컴퓨터) 에서 일할 때는 안전장치가 너무 무거워서 불편했고, 공사 현장 (서버) 으로 갈 때는 공구함 자체가 너무 무거워서 옮기기 힘들었습니다.
결과: 개발자들이 새로운 기능을 추가하려면 기존 구조를 부수고 다시 지어야 할 정도로 복잡하고 깨지기 쉬웠습니다.
🚀 2. 해결책: 새로운 '모듈형 건축 키트' (V1 SDK)
이제 팀은 **'오픈핸즈 소프트웨어 에이전트 SDK'**를 만들었습니다. 이는 마치 레고 블록이나 모듈형 건축 키트처럼 설계되었습니다.
🧩 핵심 아이디어 4 가지
1. "필요할 때만 안전모를 씁니다" (선택적 샌드박싱)
이전: 모든 작업을 격리된 방 (샌드박스) 에서만 해야 해서, 간단한 메모장 수정 같은 일에도 방을 지어야 했습니다.
지금: 평소에는 내 책상 (내 컴퓨터) 에서 자유롭게 일하다가, 위험한 작업 (예: 해킹 시도, 대용량 데이터 삭제) 만 할 때만 격리된 안전 방으로 이동합니다. 유연성과 안전을 동시에 잡았습니다.
2. "변하지 않는 설계도, 오직 하나의 기록장" (불변성 & 이벤트 소싱)
이전: 설계도 (설정) 가 여러 군데에 흩어져 있어서, 한 군데를 고르면 다른 데가 망가졌습니다.
지금:
설계도 (에이전트): 처음에 딱 만들어지면 절대 변하지 않습니다. (불변성)
기록장 (이벤트 로그): 모든 작업은 '기록'으로만 남습니다. "벽을 칩니다", "창문을 엽니다" 같은 기록이 순서대로 쌓입니다.
장점: 실수가 나면 기록을 다시 읽어서 (재생) 바로 이전 상태로 되돌릴 수 있습니다. 마치 게임의 '저장/불러오기' 기능처럼 작동합니다.
3. "건축가와 시공팀의 분업" (모듈화)
이전: 건축가 (에이전트) 가 벽을 쌓는 일, 전기 배선, 가구 배치까지 모두 다 했습니다.
지금:
SDK (핵심): 건축가의 '두뇌'만 담당합니다.
도구 (Tools): 망치, 드릴 등 구체적인 도구는 따로 패키지로 분리됩니다.
작업장 (Workspace): 현장이 내 컴퓨터인지, 클라우드 서버인지에 따라만 바뀝니다.
효과: 건축가 (핵심) 는 변하지 않고, 도구만 갈아 끼우거나 현장만 바꾸면 됩니다.
4. "누구나 쉽게 연결할 수 있는 만능 어댑터"
이전: VS Code(코드 편집기), 웹 브라우저, 명령어 창 등 각기 다른 곳에 연결하려면 코드를 완전히 다시 써야 했습니다.
지금: 하나의 코드로 작성하면, 내 컴퓨터에서 실행되든, 원격 서버에서 실행되든, 웹에서 실행되든 자동으로 맞춰집니다. 한 번 쓰고 어디든 가져갈 수 있습니다.
🛡️ 3. 보안과 신뢰: "안전한 공사 현장"
비밀 번호 관리: 에이전트가 비밀번호나 API 키를 다룰 때, 화면에 그대로 띄우는 게 아니라 *** 로 가립니다. (비밀 번호가 유출되지 않음)
위험 감지: 에이전트가 "모든 파일을 삭제합니다"라고 하면, 시스템이 "이건 위험하네요! 사용자 확인이 필요합니다"라고 멈춥니다. 사용자가 "OK"를 누르면만 실행됩니다.
실제 효과: 15 일간 실제 운영 데이터를 비교한 결과, 시스템 오류가 61% 나 줄었습니다. (예: 서버 연결 끊김, 인증 실패 등이 거의 사라짐)
📊 4. 성능: "똑똑한 건축가"는 그대로인가요?
새로운 시스템을 만들었으니 성능이 떨어지지 않을까 걱정할 수 있습니다. 하지만 결과는 다릅니다.
성능 유지: 기존 시스템과 똑같은 성능을 내면서, 새로운 기능 (예: 더 복잡한 추론이 가능한 최신 AI 모델 지원) 을 더 잘 다룹니다.
다양한 모델 지원: OpenAI, Anthropic, Google 등 100 개 이상의 다양한 AI 모델을 하나로 연결해 쓸 수 있습니다. 마치 모든 전압의 플러그를 꽂을 수 있는 어댑터처럼요.
💡 요약: 이 논문이 말하고자 하는 것
이 논문은 **"AI 에이전트를 실제로 상용화 (프로덕션) 하려면, 복잡하고 깨지기 쉬운 구조를 버리고, 모듈화되고 안전하며 유연한 구조로 바꿔야 한다"**는 것을 증명합니다.
과거: 무거운 안전장치를 항상 착용하고, 모든 것을 한 번에 처리하려다 고장 나기 쉬운 구조.
현재 (OpenHands SDK): 필요할 때만 안전장치를 착용하고, 레고처럼 부품을 갈아 끼우며, 실수해도 기록을 통해 바로 복구 가능한 튼튼하고 유연한 건축 키트.
이 도구를 통해 개발자들은 이제 AI 에이전트를 더 쉽게 만들고, 더 안전하게 배포할 수 있게 되었습니다. 마치 레고로 복잡한 성을 쌓을 때, 부러지지 않는 튼튼한 블록과 명확한 설명서를 받은 것과 같은 느낌입니다.
1. 문제 정의 (Problem)
소프트웨어 엔지니어링 분야에서 AI 에이전트 (Devin, Claude Code, OpenHands 등) 가 단순한 보조 도구를 넘어 자율적으로 복잡한 작업을 수행하는 시스템으로 진화하고 있습니다. 그러나 이러한 에이전트를 생산 환경 (Production) 에 안정적으로 배포하는 것은 다음과 같은 아키텍처적 난제들로 인해 매우 복잡합니다.
유연성 부재: 기존 시스템 (OpenHands V0) 은 단일 모노리식 (Monolithic) 아키텍처로 설계되어 연구와 프로덕션 코드가 밀접하게 결합되어 있었습니다. 이로 인해 로컬 프로토타이핑과 샌드박스 기반의 원격 실행 간의 전환이 어렵고, 새로운 기능 추가 시 기존 로직을 수정해야 하는 등 확장성이 떨어졌습니다.
보안 및 신뢰성 문제: 모든 실행을 무조건 샌드박스 (Docker 컨테이너) 내에서 수행하도록 강제한 V0 의 설계는 로컬 실행 워크플로우 (CLI 등) 를 지원하기 위해 우회 로직을 추가해야 했으며, 이로 인해 코드 중복과 불안정성이 발생했습니다. 또한, 프로세스 간 통신 (HTTP) 에 의존하여 네트워크 불안정성이나 컨테이너 충돌로 인한 실패가 빈번했습니다.
상태 관리의 복잡성: 구성 (Configuration) 이 여러 계층에 분산되어 있어 일관된 상태 관리가 어렵고, 재현 가능한 실행 (Deterministic Replay) 이 불가능했습니다.
표준화된 참조 아키텍처 부재: OpenAI, Anthropic, Google 등 주요 제공자들의 SDK 는 고립 모델, 상태 관리, 배포 가정 등에서 차이가 있어, 개발자들이 검증된 참조 설계를 찾기 어려웠습니다.
2. 방법론 및 아키텍처 (Methodology & Architecture)
OpenHands V1 은 위 문제들을 해결하기 위해 OpenHands Software Agent SDK를 도입하여 아키텍처를 완전히 재설계했습니다. 핵심 설계 원칙과 구성 요소는 다음과 같습니다.
핵심 설계 원칙 (Design Principles)
선택적 격리 (Optional Isolation): 에이전트는 기본적으로 로컬 프로세스에서 실행되지만, 안전성이 필요할 때만 샌드박스 (Docker/Kubernetes) 로 전환 가능합니다. 이는 MCP(Model Context Protocol) 의 로컬 실행 가정과 일치합니다.
무상태 기본값 및 단일 진실 공급원 (Stateless by Default, One Source of Truth): 에이전트, 도구, LLM 은 모두 불변 (Immutable) 객체로 설계되며, 모든 변경 가능한 상태는 ConversationState 객체 하나에 집중됩니다.
엄격한 관심사 분리 (Strict Separation of Concerns): 에이전트 코어 (SDK) 와 애플리케이션 (CLI, GUI 등) 을 분리하여 재사용성을 높였습니다.
이중 레이어 구성 가능성 (Two-layer Composability): 배포 패키지 (SDK, Tools, Workspace, Server) 와 기능적 구성 요소 (Tool, LLM 등) 를 독립적으로 확장 및 교체할 수 있습니다.
주요 구성 요소
4 개의 모듈식 패키지:
openhands.sdk: 에이전트, 대화, LLM, 도구 등의 핵심 추상화 및 이벤트 시스템.
openhands.tools: 구체적인 도구 구현 (MCP 통합 포함).
openhands.workspace: 로컬 및 원격 (Docker, API) 실행 환경 추상화.
openhands.agent_server: 원격 실행을 위한 REST/WebSocket API 서버.
이벤트 소싱 상태 관리 (Event-Sourced State Management): 모든 상호작용을 불변의 이벤트 로그로 기록합니다. 이는 충돌 복구, 재현 가능한 실행, 그리고 대화 중단/재개 (Pause/Resume) 를 가능하게 합니다.
다중 LLM 라우팅 및 비함수 호출 모델 지원: 100 개 이상의 LLM 제공자를 지원하며, 함수 호출을 지원하지 않는 모델도 텍스트 기반 프롬프트를 통해 에이전트 작업에 활용할 수 있도록 합니다.
보안 및 확인 (Security & Confirmation):SecurityAnalyzer 를 통해 각 도구 호출의 위험도를 평가하고, ConfirmationPolicy 를 통해 사용자의 승인 여부를 결정하는 안전 장치를 내장했습니다.
로컬 - 원격 전환 (Local-to-Remote): 동일한 에이전트 코드를 LocalWorkspace 에서 프로토타이핑하고, DockerWorkspace 를 지정하기만 하면 프로덕션 환경으로 즉시 배포할 수 있습니다.
3. 주요 기여 (Key Contributions)
생산용 에이전트 SDK 표준 제시: OpenAI, Claude, Google 의 SDK 와 비교하여 네이티브 샌드박스 실행, 라이프사이클 제어, 모델 무관한 다중 LLM 라우팅, 내장 보안 분석을 통합한 유일한 오픈소스 프레임워크를 제시했습니다.
아키텍처 재설계 (V0 → V1): 모노리식 구조에서 모듈식 SDK 로 전환하여 유연성과 안정성을 동시에 확보했습니다.
내장된 보안 및 QA 인프라: 에이전트 행동에 대한 실시간 보안 분석, 비밀 정보 (Secrets) 자동 마스킹, 그리고 학술적 벤치마크 평가를 위한 통합 테스트 하네스를 제공합니다.
오픈소스 생태계: 전체 코드와 벤치마크를 MIT 라이선스로 공개하여 커뮤니티 기여와 연구 재현성을 장려합니다.
4. 실험 결과 (Results)
논문의 실험 결과는 시스템 신뢰성과 에이전트 성능 두 가지 측면에서 검증되었습니다.
생산 환경 신뢰성 (Reliability):
15 일간의 병렬 배포 테스트에서 V1 은 V0 대비 시스템 귀속 실패 (System-attributable failures) 를 61% 감소시켰습니다 (1,000 회 대화당 78.0 건 → 30.0 건).
특히 V0 에서 발생하던 HTTP 통신 오류, 컨테이너 준비 상태 충돌 등의 인프라 오류가 V1 의 통합 실행 모델로 인해 제거되었습니다.
이벤트 소싱의 오버헤드는 미미하여, 지속성 (Persist) 지연 시간은 0.2ms 미만, 충돌 복구 시간은 20ms 미만으로 측정되었습니다.
에이전트 성능 (Performance):
14 개의 언어 모델과 5 가지 벤치마크 (SWE-Bench Verified, GAIA, SWT-Bench 등) 에서 평가되었습니다.
SWE-Bench Verified에서 Claude Sonnet 4.5 를 사용할 때 V1 은 V0 대비 8.2 포인트 향상된 성능 (72.8%) 을 보였으며, 이는 V1 아키텍처가 'Extended Thinking' 기능을 자연스럽게 통합했기 때문입니다.
전체적으로 5 개 벤치마크 중 3 개에서 SOTA(State-of-the-Art) 성능을 달성하거나 경쟁력 있는 결과를 보였습니다.
5. 의의 및 결론 (Significance)
이 논문은 OpenHands Software Agent SDK 를 통해 연구용 프로토타입에서 대규모 프로덕션 배포까지 이어지는 신뢰할 수 있는 아키텍처를 제시했다는 점에서 의의가 큽니다.
실용성: 개발자가 복잡한 인프라 설정 없이 로컬에서 에이전트를 개발하고, 최소한의 코드 변경으로 샌드박스 기반의 안전한 프로덕션 환경으로 확장할 수 있게 합니다.
확장성: 모듈식 설계와 타입 안전성 (Type Safety) 을 통해 커스텀 도구, 새로운 LLM, 보안 정책 등을 쉽게 통합할 수 있습니다.
표준화: 다양한 에이전트 SDK 간의 기능 격차를 해소하고, 보안, 상태 관리, 배포 측면에서 산업 표준으로 작용할 수 있는 참조 설계를 제공합니다.
결론적으로, OpenHands V1 은 소프트웨어 엔지니어링 에이전트의 생산성, 안정성, 그리고 확장성을 동시에 만족시키는 강력한 기반 기술로 자리매김했습니다.