주요 콘텐츠로 건너뛰기
AI 튜토리얼

Astra 및 JEV Minecraft 에이전트 실행 및 검증

Minecraft Java 1.16.5용 Astra 및 JEV 에이전트를 설치하고 구성하며 실행, 테스트, 녹화 및 검증하는 방법을 알아보세요. 이 가이드에서는 플래너-액션 아키텍처, 자격 증명 처리, 새 월드 설정, 네이티브 클라이언트 워크플로, 증거 파일, 고급 전투 및 녹화 시 고려 사항을 설명합니다.

약 19분 소요
Astra 및 JEV Minecraft 에이전트 실행 및 검증

프로젝트가 하는 일

Astra와 JEV Minecraft 에이전트는 구조화된 게임 관찰 정보와 제한된 플레이어 행동을 사용해 미리 정의된 Minecraft Java 1.16.5 경로를 완료합니다. GPT-6 Astra 또는 선택적으로 GPT-5.6 Sol이 목표, 아이템 대상, 이동 웨이포인트를 계획합니다. 그런 다음 JEV가 사용 가능한 행동을 선택하고, Mineflayer가 이동, 경로 탐색 및 일반적인 게임 프로토콜 상호작용을 수행합니다.

이는 스크린샷만을 이용한 제어가 아니며 개별 키보드 입력을 에뮬레이션하지도 않습니다. 모델은 로드된 청크의 블록과 알려진 시드에 대해 제공된 좌표를 포함한 구조화된 상태를 받습니다. 사용 가능한 행동에는 이동, 블록 하나 채굴, 드롭 아이템 수집, 제작, 상자 열기, 음식 먹기, 자기, 전투 상호작용이 포함됩니다.

가장 최근에 검증된 실행인 nether-final-08은 8분 43.300초 만에 완료되었습니다. 평화로움 난이도의 새로운 서바이벌 월드에서 빈 인벤토리로 시작해 네더를 통과했고, 첫 착지 때 침대 폭발 6회로 엔더 드래곤을 처치했으며, 체력이 가득 차고 사망 없이 출구 포털에 들어갔습니다. 이 실행에서는 JEV 결정 131회와 Astra 호출 35회가 사용되었습니다.

이 프로젝트는 공식 바닐라 서버를 사용하며 일반 플레이어 프로토콜을 통해 선택된 행동을 전송합니다. Java 드래곤 센서는 읽기 전용입니다. 정확한 드래곤 머리 위치를 보고하지만 아이템을 지급하거나, 엔티티를 이동시키거나, 체력을 변경하거나, 게임 규칙을 바꾸지는 않습니다.

주요 기능

  • 분리된 모델 역할: Astra 또는 Sol이 현재 목표를 계획하고, JEV가 현재 관찰 정보에서 제한된 행동 하나를 선택합니다.
  • 일반적인 Minecraft 상호작용: Mineflayer가 이동, 경로 탐색, 블록 상호작용, 제작, 인벤토리 작업 및 프로토콜 통신을 처리합니다.
  • 네더를 활용한 경로: 고정된 경로는 엔드 전투 전에 네더를 이동 지름길로 사용합니다.
  • 읽기 전용 드래곤 관찰: 로컬 Java 센서가 정밀한 침대 폭발 타이밍을 위해 드래곤 머리 위치를 보고하며 엔티티 상태는 수정하지 않습니다.
  • 네이티브 녹화: 숨겨진 공식 Minecraft Java 1.16.5 클라이언트가 네이티브 모델, 텍스처, 애니메이션, 인벤토리 화면, 체력, 배고픔, 공기, 핫바 상태, 들고 있는 아이템 및 드래곤 체력을 렌더링합니다.
  • 제어된 카메라 이동: 카메라 회전은 축당 초당 240도로 제한되며 가속도는 초당 960도입니다.
  • 구조화된 증거: JSONL 이벤트 로그, 상태 파일, 승리 증거, 동영상 매니페스트 및 월드 상태 검사가 이후 검증을 지원합니다.
  • 자동화된 테스트: 저장소에는 완료 이벤트, 네이티브 패킷, 행동 정책 및 경로 탐색기 취소를 검사하는 테스트가 포함되어 있습니다.

아키텍처 및 모델 구성

기본 플래너 모델은 openai/gpt-6-astra이며 /api/v1/chat/completions를 통해 호출됩니다. PLANNER_MODEL 환경 변수를 통해 openai/gpt-5.6-sol을 선택할 수 있습니다. JEV는 /api/alpha/decisions를 통해 typesafe/jev-1.13을 사용합니다.

플래너가 임의의 시퀀스를 직접 수행하지는 않습니다. 플래너는 현재 목표, 원하는 아이템 및 웨이포인트를 설정합니다. JEV는 현재 구조화된 관찰 정보를 평가하고 허용된 행동을 선택합니다. 이러한 분리를 통해 개별 결정은 제한하면서도 전체 실행은 더 긴 계획을 따를 수 있습니다.

요구 사항 및 주요 제한 사항

실행 및 네이티브 렌더링 스크립트는 macOS에서 개발되었습니다. 다른 운영체제에서는 런타임 경로, Java 위치 및 로컬 서버 설정을 조정해야 합니다. 제공된 네이티브 실행 스크립트는 자체 로컬 Java 17 런타임을 사용합니다.

Node.js와 npm, 네이티브 클라이언트 스크립트용 Python 3, 호환 가능한 Java 런타임, Google Application Default Credentials, OpenRouter 키가 포함된 Google Secret Manager 시크릿에 대한 액세스 권한 및 충분한 OpenRouter 크레딧이 필요합니다. Minecraft 바이너리, 다운로드한 런타임, 저장된 월드, 녹화 파일 및 자격 증명은 의도적으로 Git에서 제외됩니다.

문서화된 게임 구성은 다음과 같습니다.

  • 시드: 8398967436125155523
  • 모드: Survival
  • 검증된 녹화에 사용된 난이도: Peaceful
  • 활성 엔드 포털 중심: -1130, 34, 856
  • 주 서버: 127.0.0.1:25576
  • 상태 엔드포인트: http://127.0.0.1:3078
  • 에이전트가 사용하는 로컬 드래곤 센서 엔드포인트: http://127.0.0.1:3093
  • 네이티브 프로토콜 미러 포트: 25578

이 시드에는 마을, 흑요석 21개가 들어 있는 보급 상자 3개 및 자연적으로 활성화된 엔드 포털이 있습니다. 문서화된 경로에는 블레이즈 막대가 필요하지 않습니다. 좌표는 별도의 테스트 월드에서 조사했지만 최종 실행의 이동과 설치는 일반적인 플레이어 상호작용을 사용합니다.

1단계: Node.js 종속성 설치

저장소 루트에서 프로젝트 패키지를 설치합니다.

npm install

이 명령은 에이전트, 모델 릴레이, 경로 로직, 증거 도구 및 테스트에 사용되는 JavaScript 종속성을 설치합니다.

2단계: 보안 모델 액세스 구성

에이전트는 일반적인 OPENROUTER_API_KEY 환경 변수를 의도적으로 무시합니다. 대신 모델 호출 시 Google Secret Manager에서 키를 불러와 프로세스 메모리에만 보관합니다. 키가 소스 파일이나 실행 로그에 나타나서는 안 됩니다.

  1. model-relay.mjs와 models.mjs를 엽니다.
  2. 원래 배포에 사용된 Google Cloud 프로젝트 및 시크릿 참조를 자신의 프로젝트에 해당하는 참조로 교체합니다.
  3. Google 애플리케이션 기본 자격 증명을 사용해 로컬에서 인증합니다.
  4. 인증된 ID에 선택한 시크릿에 액세스할 수 있는 권한을 부여합니다.
  5. 저장소의 릴레이 설정에 따라 모델 릴레이를 시작합니다.
  6. 에이전트를 실행할 때 릴레이 URL을 설정합니다.
MODEL_RELAY=http://127.0.0.1:3099

OpenRouter 키를 소스 코드, 셸 스크립트, 이벤트 로그 또는 실행 메타데이터에 붙여 넣지 마세요. 이 프로젝트는 Secret Manager에서 키를 가져와 프로세스 메모리에 보관하도록 설계되었습니다.

3단계: 서버 및 드래곤 옵저버 준비

호환되는 바닐라 Minecraft Java 1.16.5 서버 JAR을 server/server.jar에 배치합니다. README에 따르면 설치된 Minecraft Java 런타임으로 이 서버를 실행할 수 있습니다.

드래곤 옵저버는 observer/DragonObserver.java에 구현되어 있습니다. 다음 명령으로 빌드합니다.

./build-observer.sh

다음 명령으로 메인 서버와 읽기 전용 센서를 시작합니다.

./start-server.sh

옵저버는 서버의 드래곤 틱에 로컬 전용 관찰 호출을 추가합니다. 옵저버는 읽기 전용으로 유지해야 하며, 드래곤 AI나 플레이어 및 엔티티 상태를 변경하지 않습니다.

완전히 새로운 월드 생성

새 실행 디렉터리를 만든다고 해서 Minecraft 월드가 초기화되지는 않습니다. 새로 기록하기 전에 서버를 중지하고 server/server.properties에서 사용하지 않은 level-name을 선택합니다. 설정된 시드는 변경하지 않은 채 서버를 다시 시작합니다.

실행 로그 디렉터리에도 동일한 새 이름을 사용합니다. 이전 실행의 증거에 포함된 월드는 보존합니다.

4단계: 네이티브 클라이언트 설치 및 빌드

숨겨진 네이티브 클라이언트는 새 기록에 사용되는 공식 Minecraft 렌더링을 제공합니다. Python 측 종속 항목을 설치하고 디스플레이 및 캡처 어댑터를 빌드합니다.

python3 native-client/install.py
./native-client/build.sh

클라이언트는 격리된 게임 디렉터리를 사용하므로 사용자의 일반 Minecraft 설정을 덮어쓰지 않습니다. 데스크톱 포커스와 커서 제어는 비활성화되며, 캡처는 데스크톱을 녹화하는 대신 게임 프레임버퍼를 읽습니다.

5단계: 실행 구성 고정

고유 식별자를 선택합니다. 아래에서는 NEW_RUN으로 표시합니다. 에이전트를 실행하기 전에 다음 명령으로 실행을 고정합니다.

node optimization/nether/freeze-run.mjs NEW_RUN

최종 경로는 optimization/nether/config.json에 정의되어 있습니다. 실행을 고정하면 해당 실행에서 생성된 로그 및 기록과 연결된 구성을 보존하는 데 도움이 됩니다.

6단계: 에이전트 시작

저장소 루트에서 에이전트를 실행합니다. 다음 명령은 Astra를 선택하고, 네이티브 뷰 및 레코더를 활성화하며, 네이티브 클라이언트를 기다린 후 드래곤 센서에 연결합니다.

PLANNER_MODEL=openai/gpt-6-astra RUN_ID=NEW_RUN \
NATIVE_VIEW=1 WAIT_NATIVE=1 NATIVE_RECORD=1 \
DRAGON_SENSOR_URL=http://127.0.0.1:3093 node nether-agent.mjs

릴레이 URL이 프로세스 환경에 이미 설정되어 있지 않다면 다음과 같이 함께 지정합니다.

MODEL_RELAY=http://127.0.0.1:3099 \
PLANNER_MODEL=openai/gpt-6-astra RUN_ID=NEW_RUN \
NATIVE_VIEW=1 WAIT_NATIVE=1 NATIVE_RECORD=1 \
DRAGON_SENSOR_URL=http://127.0.0.1:3093 node nether-agent.mjs

Sol을 플래너로 사용하려면 모델 값을 변경합니다.

PLANNER_MODEL=openai/gpt-5.6-sol

7단계: 숨겨진 Minecraft 클라이언트 실행

로컬 프로토콜 미러가 포트 25578에서 수신 대기할 때까지 기다립니다. 그런 다음 다른 터미널을 열고 실행합니다.

python3 native-client/launch.py

WAIT_NATIVE=1이 활성화되어 있으므로 에이전트는 첫 번째 행동을 수행하기 전에 숨겨진 클라이언트와 레코더를 기다립니다. 레코더는 출구 포털 이벤트 후 중지됩니다.

생성되는 캡처는 오디오 없이 960 × 540 해상도, 초당 20프레임으로 제작됩니다. 체력, 허기, 핫바, 들고 있는 아이템, 인벤토리 및 제작 화면, 네이티브 애니메이션, 드래곤 체력을 표시할 수 있습니다.

실행 모니터링 및 안전한 중지

현재 상태는 로컬 상태 엔드포인트에서 확인할 수 있습니다.

http://127.0.0.1:3078

현재 진행 상황은 status.json에도 기록됩니다. 행동 경계에서 중지를 요청하려면 다음 파일을 생성합니다.

runs/NEW_RUN/stop

실행이 끝난 직후 네이티브 클라이언트를 종료하지 마세요. 다음 녹화 완료 마커가 생성될 때까지 기다립니다.

runs/NEW_RUN/full-playthrough.mp4.finished.json

이렇게 하면 최종 캡처가 잘리거나 손상되는 것을 방지할 수 있습니다.

생성된 증거 이해하기

각 실행의 증거는 runs/<run> 아래에 저장됩니다. 가장 중요한 파일은 다음과 같습니다.

  • events.jsonl: 요청, 모델 응답, 선택한 행동, 게임 결과 및 완료 이벤트
  • status.json: 최신 실행 진행 상황
  • victory.json: 필요한 드래곤 사망 및 출구 포털 증거가 있을 때만 생성됨
  • full-playthrough.mp4: 녹화가 활성화된 경우의 네이티브 녹화 파일
  • full-playthrough.mp4.finished.json: 녹화 최종 처리가 완료되었음을 확인하는 파일

드래곤 사망 증거는 처치 발전 과제일 수도 있고, 드래곤의 사망 단계와 함께 서버가 보고한 체력 0일 수도 있습니다. 침대 처치에서는 처치 발전 과제가 누락될 수 있으므로 이 차이가 중요합니다. Java 1.16.5에서는 출구 이벤트가 숫자 이유 코드 4를 사용합니다.

유효한 최종 검토는 victory.json에만 의존해서는 안 됩니다. 월드의 DragonFight 상태와 동영상도 함께 확인해야 합니다.

자동 검사 실행

완료 이벤트, 네이티브 미러 패킷, 액션 정책 및 경로 찾기 취소를 확인하려면 저장소의 Node 테스트 스위트를 사용하세요:

node --test evidence.test.mjs native-mirror.test.mjs optimization/*.test.mjs optimization/pass-2/policy.test.mjs optimization/nether/*.test.mjs

이 테스트는 실제 환경 검증을 대체하지 않습니다. 이동, 제작, 전투, 서버 통합 및 녹화는 여전히 실행 중인 Minecraft 서버에서 테스트해야 합니다.

End 전투 작동 방식

end-combat.mjs의 전투 구현은 JEV가 선택할 수 있는 제한된 침대 공격 하나를 제공합니다. 이 액션은 침대 하나를 설치하고, 침대를 조준한 다음, 관측된 드래곤 머리가 설정된 공격 범위에 들어올 때까지 기다렸다가 사용 명령을 한 번 전송합니다.

플레이어가 엄폐를 잃거나 드래곤의 숨결이 엄폐 영역에 들어오면 액션이 중단됩니다. README에 따르면 사용 전에 조준하고 공격 범위를 좁히는 방식으로 튜닝한 결과, 침대 하나당 피해량이 11에서 46으로 향상되었습니다.

최종 검증 실행에서는 첫 착지 시 침대 폭발 6회로 드래곤을 처치했습니다. 그러나 드래곤의 비행 및 착지 시점은 실행마다 달라지므로 완료 시간이 동일하다고 보장할 수 없습니다.

전투 실험실 올바르게 사용하기

combat-lab 디렉터리는 별도의 테스트 환경입니다. 미리 준비된 위치, 인벤토리 및 기타 테스트 변경 사항을 사용할 수 있습니다. 하드코딩된 드라이버인 combat-probe.mjs는 포트 25577을 사용하며 어느 모델도 호출하지 않습니다.

전투 실험실 결과를 완전한 모델 제어 서바이벌 실행 결과로 제시하지 마세요. 실험실 결과는 빈 인벤토리에서 시작하는 전체 경로가 아니라 격리된 전투 동작을 검증합니다.

고급 녹화 및 검증 팁

정보 오버레이 추가 및 검증

저장소에는 모델 이름, 경과 시간(밀리초), XYZ 좌표, 플래너 목표 및 선택된 액션을 표시하는 반투명 상단 배너를 추가하는 오버레이 작업 흐름이 문서화되어 있습니다. 이러한 레이블은 기록된 모델 응답과 게임 이벤트를 기반으로 합니다.

문서에 나온 예시 실행에서 다음 명령으로 오버레이를 생성하고 검증하세요:

node overlay.mjs nether-final-02
node verify-run.mjs nether-final-02 nether-final-02 full-playthrough-overlay.mp4

이전 Prismarine Viewer 녹화의 문서화된 명령은 다음과 같습니다:

node assemble-video.mjs recorded-06
node verify-run.mjs recorded-06

이전 recorded-06 작업 흐름은 Prismarine Viewer와 사용자 지정 HUD를 사용했습니다. 새 녹화는 읽기 전용 프로토콜 미러를 통해 공식 Minecraft Java 1.16.5 클라이언트를 사용합니다.

일시 중지 및 코드 업데이트 이력 보존

에이전트에 코드 업데이트가 필요해 녹화에 여러 캡처 파일이 포함된 경우, 활성 게임플레이 구간을 모두 보존하세요. 통합 영상에서 각 업데이트 일시 중지를 표시하고 모든 사망 및 일시 중지를 보고하세요. 그러한 실행은 실제로 중단되지 않았거나 사망이 없지 않은 한 중단 없음 또는 무사망 실행으로 설명해서는 안 됩니다.

안전하지 않은 포털 진입 전략 피하기

실험실 테스트에서 End 포털로 길게 낙하하면 낙하 피해가 End까지 이어질 수 있음이 확인되었습니다. 녹화된 경로는 이 전략을 거부하고 대신 짧고 확인된 하향 채굴 단계를 사용했습니다. 경로 동작을 수정할 때도 이 안전 제약을 유지하세요.

승리 상태를 종료 상태로 유지

현재 구현은 승리 후 다른 게임 액션이 실행되지 않도록 합니다. 액션 루프를 수정하더라도 이 동작을 유지하세요. 승리 후 액션은 로그와 녹화를 해석하기 어렵게 만들 수 있습니다.

로컬 산출물을 Git에서 제외

녹화 및 생성된 증거는 설계상 로컬에만 남습니다. 최신 영상의 문서화된 경로는 runs/nether-final-08/full-playthrough-banner.mp4이며, 검증 결과, 시간 비교 및 액션 로그도 같은 실행 디렉터리에 있습니다. 녹화 파일, 다운로드한 런타임, 서버 바이너리, 월드 또는 인증 정보를 커밋하지 마세요.

문제 해결 체크리스트

  • 에이전트가 시작되지 않음: 미러가 포트 25578에서 수신 중이고 네이티브 클라이언트가 연결되었는지 확인하세요. WAIT_NATIVE=1을 사용하면 대기하는 것이 정상입니다.
  • 모델 요청 실패: Google Application Default Credentials, Secret Manager 권한, model-relay.mjs 및 models.mjs의 프로젝트와 시크릿 참조, 포트 3099의 릴레이 가용성 및 OpenRouter 크레딧을 확인하세요.
  • 실행이 이전 월드에서 시작됨: 서버를 중지하고 실제로 사용되지 않은 level-name을 설정하세요. 새 실행 디렉터리만 만드는 것으로는 충분하지 않습니다.
  • 드래곤 관측을 사용할 수 없음: 옵저버를 빌드하고 센서와 함께 서버를 시작한 뒤, 에이전트가 DRAGON_SENSOR_URL=http://127.0.0.1:3093을 사용하는지 확인하세요.
  • 완료된 녹화 마커가 나타나지 않음: full-playthrough.mp4.finished.json이 작성될 때까지 네이티브 클라이언트를 실행 상태로 유지하세요.
  • 플랫폼별 경로 실패: 제공된 스크립트는 macOS에서 개발되었으므로 Java, Minecraft 런타임, 네이티브 클라이언트 및 서버 경로를 조정하세요.

결론

Astra 및 JEV 프로젝트는 제한 없이 게임하는 봇이 아니라 구조화되고 증거 중심적인 Minecraft 에이전트를 보여줍니다. Astra 또는 Sol이 경로를 계획하고, JEV가 제한된 액션을 선택하며, Mineflayer가 일반 프로토콜을 통해 이를 실행하고, 읽기 전용 센서가 정밀한 드래곤 전투를 지원합니다. 신뢰할 수 있는 실행을 위해서는 신중한 인증 정보 관리, 실제로 새로 생성된 월드, 동기화된 네이티브 녹화, 보존된 로그, 자동화된 테스트, 그리고 게임 상태와 영상 증거 모두에 대한 최종 검토가 필요합니다.

관련 기반 기술은 TypeSafe 공식 소개, Mineflayer 저장소, Astra 공식 모델 문서를 참조하세요.