hera-agent-unity의 구성 요소와 핵심 기능
hera-agent-unity는 AI 에이전트가 Unity 에디터의 상태를 실시간으로 확인하고 제어할 수 있도록 돕는 CLI 도구다. Unity 6(6000.0+) 버전을 지원하며, 기존의 상용 버전인 hera-agent-pro의 모든 기능을 포함해 MIT 라이선스로 배포된다.
기술적 구성은 Go 언어로 작성된 단일 바이너리 1개와 C# 기반의 UPM(Unity Package Manager) 패키지 1개로 이루어진다. 별도의 런타임 의존성이 없으며, Unity 에디터를 실행하면 localhost HTTP를 통해 즉시 연결되는 구조다. 특히 Python, WebSocket, JSON-RPC와 같은 외부 미들웨어나 프로토콜 스택을 요구하지 않는 것이 특징이다.
제공하는 핵심 API 기능은 다음과 같다.
- `exec`: Unity 내부에서 임의의 C# 코드를 실행한다. 에디터와 런타임 전체에 접근 가능하며, Roslyn 컴파일러를 통해 코드를 컴파일하고 캐싱하여 동일 코드 재실행 시 지연시간을 줄인다.
- `console`, `scene`, `test`, `profiler`: 실제 콘솔 로그를 종류별로 읽거나 씬(Scene) 조작, PlayMode 테스트 실행, 터미널 기반의 프로파일러 데이터 조회를 수행한다.
- `describe_type`, `find_method`, `unity_docs`: 리플렉션을 통해 살아있는 어셈블리를 분석한다. 특히 31,581개의 Unity 6 ScriptReference 데이터를 패키지에 내장해 네트워크 연결이나 API 호출 제한(Rate Limit) 없이 오프라인으로 조회할 수 있다.
- `manage_gameobject`, `components`, `prefab`, `material`, `ui`: GameObject, 컴포넌트, 프리팹, 머티리얼, uGUI 요소를 C# 보일러플레이트 코드 작성 없이 API 호출만으로 편집한다.
- `batch`: 여러 명령어를 하나의 HTTP 요청으로 묶어 원자적으로 실행하며, 주로 CI(지속적 통합)나 자동화 파이프라인에서 사용된다.
작동 메커니즘과 UI 번역 파이프라인
통신 구조는 기존의 MCP(Model Context Protocol) 방식과 차별화된다. MCP가 JSON-RPC over stdio 방식을 사용하는 것과 달리, hera-agent-unity는 직접적인 HTTP POST 방식을 채택했다. 이로 인해 도메인 리로드 시 복잡한 재연결 로직이 필요 없는 스테이트리스(Stateless) 구조를 가지며, 파일시스템 버스를 통해 상태를 관리한다.
AI 에이전트가 가장 어려워하는 uGUI(Unity UI) 제어는 `ui_doc` 기능을 통해 처리한다. 에이전트가 HTML과 유사한 형태의 JSON IR(중간 표현식)로 UI를 설계하면, Hera가 이를 실제 uGUI의 anchor, pivot, 레이아웃 설정으로 정확히 번역해 적용한다.
이 과정은 '추측 대신 실측'이라는 루프로 작동한다.
1. **sample**: 레퍼런스 스크린샷에서 색상 및 위치 정보를 측정한다.
2. **IR 작성**: 측정값을 기반으로 JSON IR을 생성한다.
3. **apply**: 생성된 IR을 Unity uGUI로 적용한다.
4. **capture**: 적용된 결과를 다시 렌더링하여 캡처한다.
5. **compare & modify**: 원본 스크린샷과 캡처본을 비교해 오차를 수정한다.
이 파이프라인은 외부 의존성 없이 절차적 스프라이트 생성을 수행하며, 컴파일 타임에 `com.unity.ugui`에 대한 의존성을 가지지 않아 가볍게 동작한다.
개발 환경 도입 시 고려사항과 확장 방법
개발자가 체감하는 가장 큰 변화는 설치 및 실행 환경의 단순화다. 기존 MCP 기반 도구들이 Python 설치, uv 패키지 관리, FastMCP 설정 및 별도의 설정 파일을 요구했던 것과 달리, 단일 바이너리 실행만으로 환경 구축이 끝난다. 이 덕분에 특정 MCP 클라이언트에 종속되지 않고 Claude Code, Codex, Cursor 등 셸 명령 실행이 가능한 모든 AI 에이전트에서 즉시 사용할 수 있다.
실무자가 기능을 확장하고 싶을 때는 `[HeraTool]` 어트리뷰트를 사용한다. 별도의 등록 과정이나 코드 생성(Code Generation) 단계 없이, C# 클래스에 해당 어트리뷰트를 선언하는 것만으로 AI 에이전트가 자동으로 도구를 발견하고 호출할 수 있는 구조다.
운영 관점에서는 AI가 학습 데이터에 의존해 Unity API를 '추측'하여 코드를 작성하던 방식에서, 실제 에디터 런타임에 코드를 던져 실행 결과를 확인하는 '검증' 방식으로 워크플로우를 전환해야 한다. 이는 특히 버전별로 API 변경이 잦은 Unity 환경에서 LLM의 할루시네이션(환각 현상)을 물리적으로 차단하는 효과를 준다.
