[Unity] AI Agent 연동 구조 이해하기 Plugin / CLI / Pipeline package

AI 에이전트로 Unity 컨텐츠를 보다 효과적으로 개발하고, Unity 에디터와 직접 상호작용하기 위해서는 이 사이를 연결하는 여러 도구와 계층이 필요하다.

 

Unity 에서는 이를 위해 공식 에이전트용 플러그인, Unity CLI, Unity Pipeline package 를 제공하며, 이들은 각각 가이드 제공, 명령 전달, 에디터 내부 실행을 담당하여 하나의 연동 구조를 이룬다.

 

각 구성 요소의 역할과 동작 원리를 살펴보고, 에이전트가 어떤 과정을 거쳐서 Unity 에디터를 조작하는지 알아보자.

 

 

Unity Plugin

Unity Plugin은 Unity의 공식 게임 개발 플러그인으로, 서드파티 에이전트용 Unity 스킬 세트를 추가한다.

 

스킬은 권장 방식에 기반한 문서화된 가이드이며, 이를 활용해 Unity 게임을 개발하거나, 수익화하거나, 운영할 수 있다.

이 스킬들은 에이전트가 프로젝트를 직접 변경하도록 한다. 스크립트, 씬, 에셋을 수정하며, Unity CLI를 사용할 수 있는 경우 열려 있는 에디터에서 C#을 실행한다.

일반적으로 이런 스킬을 사용하려면 에이전트에게 자연어로 요청하거나 특정 스킬을 직접 호출하면 된다.

 

이 플러그인은 Unity Asset Store 나 Package Manager 에서 설치하는 것이 아닌, 각 에이전트 서비스에서 설치해야 한다.

현재 Unity 6 이상인 프로젝트에서 사용 가능하며, Claude Code, Codex, Grok, Antigravity에서 사용할 수 있다.

 

스킬 목록

• 2D / 3D 물리
• 타일 팔레트
• 현지화
• 스프라이트 아틀라스 관리
• 최적화 (TMP, 웹, 오디오)
• 인앱 결제 구현
• 멀티플레이 서비스 셋업
• 오디오 셋업
• UI (UI Toolkit, UGUI, IMGUI)
• 빌드
• 패키지 매니징
• URP 후처리
• Unity CLI

이외의 모든 스킬 목록은 공식 GitHub 저장소에서 확인할 수 있다.

https://github.com/Unity-Technologies/unity-agent-plugin/tree/main/skills

unity-agent-plugin/skills at main · Unity-Technologies/unity-agent-plugin

 

 

플레이모드 검증 루프

스킬 중에는 플레이모드 검증 루프(playmode-verification-loop)가 있다.

 

에이전트가 실제로 게임을 Play Mode에서 돌려서 검증해야 하는 작업을 할 때 쓰는 절차로, 에이전트 자체의 Computer Use 기능을 사용하지 않고도 Play Mode 테스트를 자동화한다.

 

화면 검증도 Unity CLI 커맨드를 통해 Game View를 직접 캡처하여 검증하기 때문에 마우스로 조작하지 않는다.

다만, 스크린샷 만 보고 정상 실행했다고 판단하지 않는다. 멈춘 게임도 정상처럼 캡처될 수 있기 때문에 `Time.frameCount`가 실제로 증가하는지도 확인하도록 되어있다.

 

핵심 흐름은 아래와 같다.

1. Editor 연결 확인
2. Play Mode가 이미 켜져 있는지 확인
3. Agent가 직접 실행할 세션이면 auto-tick + runInBackground 설정
4. Play Mode 시작
5. Pipeline 재연결 대기
6. Time.frameCount가 실제로 증가하는지 확인
7. Game View 캡처
8. Console error 확인
9. 필요하면 실행 중 C# 조정
10. Agent가 시작한 세션이면 종료 및 설정 복원

 

 

플러그인 사용 Best Practice

다음 방법을 따르면 Unity 플러그인을 더 효과적으로 사용할 수 있다.

• UI 관련 요청에서는 UI 프레임워크 이름을 명시한다. (UI Toolkit 이나 UGUI) 어느 경우든 에이전트가 추측하도록 두는 것보다 처음부터 명시하는 것이 더 효율적이다.
• 결과가 잘못된 것처럼 보이면 에이전트에게 해당 스킬의 레퍼런스 파일을 읽도록 요청한다. 에이전트가 이 단계를 건너뛰면 출력 결과가 잘못되는 경우가 많다.
• 에이전트가 추가 확인 질문을 할 수 있다는 점을 예상한다. 플러그인을 설치하면 에이전트는 임의로 가정해서 변경하기보다 변경 전에 질문한다. 에이전트를 대화형 서비스가 아닌 다른 파이프라인에서 실행한다면 에이전트의 질문이 작업을 중단시킬 수 있으므로, 추가 질문이 필요하지 않을 정도로 충분한 세부 정보를 프롬프트에 포함한다.
• 스킬이 자동으로 실행되지 않는다면 스킬 이름을 명시한다. 일부 에이전트는 사용자가 자연어로 작성한 지시와 스킬 사이의 연관성을 파악하지 못 할 수 있다.
• 모든 변경 사항이 기록되는 것은 아니며 에디터에서 되돌릴 수 없는 변경도 있으므로, 프로젝트를 버전 관리 시스템으로 관리하고 큰 변경을 요청하기 전에 커밋해 두는 것이 좋다.

 

Unity CLI와 함께 사용할 때 가장 효과적이다.

스킬 중 상당수는 열려 있는 Unity 에디터를 직접 조작한다. 씬이나 에셋 파일을 직접 수정하는 대신, GameObject를 생성하고, Import Settings를 변경하고, 에디터에서 C#을 실행하고, 그 결과를 확인할 수 있다.

이 작업은 Unity의 커맨드라인 도구인 Unity CLI를 통해 수행한다. 이는 에디터 설치, 프로젝트 생성 및 열기, 빌드와 테스트 실행 기능도 제공한다.

따로 설정할 필요는 없다. 어떤 작업에 CLI가 필요한 경우, 에이전트가 CLI의 설치 여부를 확인하고 사용한다.

 

 

Unity CLI

Unity CLI는 터미널에서 Unity 에디터와 모듈을 설치하고 관리하기 위한 독립형 커맨드라인 도구다.

 

Unity Hub를 설치하면 기본적으로 Unity CLI를 설치하고 업데이트한다. 하지만 독립된 바이너리로 배포되므로 Unity Hub와 별개로 설치, 업데이트, 사용될 수 있다.

 

전체 Unity Hub를 설치할 필요가 없는 CI 환경 및 빌드 머신, 구조화된 출력과 예측 가능한 종료 코드가 필요한 스크립팅 및 자동화 환경에서 사용하기 적합하다.

 

Unity CLI를 사용해 Unity 에디터를 제어하려면, Unity Pipeline package를 설치하고 설정해야 한다.

 

다음은 자주 사용되는 기본적인 커맨드들이다.

unity --help                                # 도움말
unity install lts                           # 최신 LTS 에디터 설치
unity install-modules -e 6000.3.7f1 -m ios  # iOS 모듈 추가
unity editors -i                            # 설치된 에디터들 리스트업
unity open ./MyProject                      # 프로젝트 열기
unity shell                                 # 하나의 shell에서 여러 명령 실행할 수 있도록 shell을 실행
unity doctor                                # 현재 상태 분석 스냅샷 출력

 

이외의 모든 커맨드는 아래 레퍼런스에서 확인할 수 있다.

https://docs.unity.com/en-us/unity-cli/unity-cli-reference?utm_source=chatgpt.com

Unity command-line interface (CLI) reference • Unity command-line interface (CLI) • Unity Docs

 

 

Unity Pipeline package

Unity Pipeline 패키지는 Unity CLI와 함께 동작하며, CLI가 연결할 수 있는 에디터 내부 로컬 HTTP 서버를 추가해 현재 실행 중인 Unity 에디터와 상호작용할 수 있도록 한다.

이를 통해 CI, 스크립팅, AI 에이전트 작업에 활용할 수 있다.

 

패키지를 설치하면 CLI가 에디터에 연결해 에디터 컨텍스트 안에서 명령을 실행할 수 있다. CLI와 Pipeline 패키지는 서로 다른 목적을 가지지만, 실행 중인 Unity 프로젝트의 워크플로를 자동화할 때는 둘을 함께 사용한다.

 

Unity Pipeline 패키지는 UPM(Unity Package Manager)에서 com.unity.pipeline 으로 설치할 수 있으며, Plugin이나 CLI처럼 전역적으로 설치되는 것이 아닌, 각 프로젝트마다 개별 import 해야한다.

 

이후 에디터가 로드되면 로컬 서버를 자동으로 시작한다.

 

 

Pipeline 서버

HTTP 요청을 보낼 수 있는 클라이언트라면 어떤 언어로 작성되었든 Unity를 제어할 수 있다. 기본적으로 서버는 localhost에 바인딩되므로 클라이언트는 에디터와 동일한 머신에서 실행된다. 원격 클라이언트는 사용자가 노출한 네트워크 경로를 통해 접근할 수 있다.

 

Pipeline 패키지는 두 개의 서버를 제공한다.

• Editor server
  • Play Mode, 상태 확인, 재컴파일, 테스트 실행, 프로젝트 설정 등을 담당한다.
• Runtime server
  • Runtime Pipeline Manager를 통해 실행 중인 빌드에 대한 실시간 수정을 담당한다.
  • 빌드를 실행한 상태에서 시간을 느리게 하거나, 일시 정지할 수 있고, 런타임에서 값을 변경하고 Transform 크기나 위치를 변경할 수 있으며, 에셋과 효과를 교체할 수 있다.

 

 

구성 요소

• commands
  • 각 command는 프로젝트 내부의 함수이며, Unity가 자동으로 등록할 수 있도록 태그가 지정되어 있다.
  • 기본 제공 command는 Play Mode, 상태 확인, 재컴파일, 테스트 실행 등이며, 사용자 정의 command를 추가할 수 있다.
• eval
  • 실행 중인 Unity 인스턴스 내부에서 일회성 작업을 위해 C#을 직접 실행한다.
  • 임의의 C# 코드를 실행할 수 있으며 보안 토큰으로 보호된다. 원격 코드 실행과 동일하게 취급하고, 로컬 개발 환경에서만 사용해야 한다.

 

unity command

 

패키지가 설치된 상태에서 실행 중인 에디터에 연결하고 자동화할 수 있는 명령 목록을 확인할 수 있다.

 

unity command editor_play

unity command run_tests

unity command list_build_targets

unity command screenshot

 

Play Mode에 진입하거나, 테스트를 실행하거나, 빌드 타겟을 나열하거나, 스크린샷을 캡처할 수 있다.

 

이외에도 unity list 를 실행하면 씬, Prefab, Material, Animation, Lighting/NavMesh bake, Build, Screenshot, Package 등을 포함한 전체 기본 명령 목록을 확인할 수 있다.

 

사용자 정의 명령을 사용하면, 일련의 작업을 하나로 묶어 커맨드라인에서 한 번에 호출할 수도 있다.

 

Pipeline 에서 제공하는 모든 commands는 아래 공식 문서에서 확인할 수 있다.

https://docs.unity3d.com/Packages/com.unity.pipeline@0.5/manual/index.html

 

 

에이전트에서의 활용

모든 command는 CLI 또는 MCP 모드를 통해 어떤 에이전트에서도 사용할 수 있으며, 에이전트는 두 가지 방식을 사용할 수 있다.

• 반복 가능한 작업에는 결정적인 이름이 있는 command 사용
• 아직 command가 없는 일회성 작업에는 eval 사용

 

예를 들어 에이전트가 eval을 사용해 무언가를 만들거나 수정한 다음, 결정적인 command를 실행해 해당 기능을 테스트하고, 스크린샷을 캡처하고, 이미지를 프롬프트와 비교해 원하는 결과가 나올 때까지 반복할 수 있다.

 

eval 은 토큰으로 보호되는 임의 C# 실행 기능이므로 에이전트가 접근할 수 있는 범위를 제한해야 한다.

 

Unity CLI와 Pipeline 패키지는 출시된 게임이 아니라 로컬 개발 환경을 위해 만들어졌다.

기본적으로 모든 것은 사용자의 머신 안에서만 동작하며 개발 중에만 실행된다.

 

eval을 통한 live code 실행은 프로젝트별 access key로 보호되므로, 에이전트가 해당 키 없이 Editor에 임의의 C#을 실행할 수 없다.

 

 

흐름 정리

 

사용자가 AI 에이전트에게 자연어로 작업을 지시한다.

 

AI 에이전트는 이 요청을 해석하고, 어떤 작업이 필요한지 판단한다. 이때 Unity Plugin에 포함된 스킬과 레퍼런스를 참고해서 Unity에서 어떤 방식으로 작업해야 하는지 결정한다.

 

작업 방식이 결정되면 AI 에이전트는 Unity CLI를 도구로 사용한다. CLI를 통해 필요한 Unity 명령을 실행하고, 에디터 제어 요청을 보낸다.

 

이 요청은 HTTP/JSON 형태로 Unity 에디터 쪽에 전달된다. 에디터에는 Unity Pipeline 패키지가 설치되어 있고, 이 패키지가 로컬 HTTP 서버를 실행해 CLI의 요청을 받게 된다.

 

로컬 HTTP 서버는 요청 내용을 바탕으로 Unity 에디터 API를 호출해 실제 작업을 수행한다.

 

 

 

참고 문헌

https://docs.unity.com/en-us/ai/unity-plugin/about-unity-plugin?utm_source=chatgpt.com

https://docs.unity.com/en-us/ai/unity-plugin/codex?utm_source=chatgpt.com

https://docs.unity.com/en-us/unity-cli/unity-cli

https://docs.unity.com/en-us/unity-cli/use-unity-cli?utm_source=chatgpt.com

https://docs.unity.com/en-us/unity-production-pipeline/local-tools-cli/unity-cli-pipeline-package?utm_source=chatgpt.com

https://unity.com/vn/resources/unity-pipeline-cli-technical-walkthrough?utm_source=chatgpt.com