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

Agent Office 3D 튜토리얼: AI 코딩 에이전트를 3D 사무실 직원으로 만들기

이 튜토리얼에서는 Agent Office 3D를 설치하고 데모 사무실을 실행한 뒤 회사와 직원 정보를 설정합니다. 또한 Herdr를 연결하거나 Minecraft를 선택하고, 에이전트 상태, 터미널 출력 및 보안 설정을 익힐 수 있습니다.

약 13분 소요
Agent Office 3D 튜토리얼: AI 코딩 에이전트를 3D 사무실 직원으로

Agent Office 3D란?

Agent Office 3D는 로컬에서 실행되는 로우 폴리 3D 사무실로, AI Coding Agent를 사무실 직원으로 표시합니다. 각 Agent가 작업 중인지, 유휴 상태인지, 작업을 완료하고 대기 중인지, 또는 확인이 필요한 권한 프롬프트에서 멈췄는지 한눈에 확인할 수 있습니다.

프로젝트는 기본적으로 데모 데이터를 사용하므로 Agent를 먼저 연결할 필요가 없습니다. 유휴 직원은 커피를 내리거나 물을 마시고, 러닝머신을 사용하거나 스트레칭을 하고, 졸거나 내장 미니게임을 즐깁니다. Minecraft를 활성화하면 직원이 Mineflayer 봇을 통해 로컬 월드에 들어갈 수도 있습니다.

화면에 표시되는 직원, 작업, 프로젝트 및 금액은 모두 데모 데이터이며 실제 업무 정보가 아닙니다.

주요 기능

  • 실시간 직원 상태: 각 Agent에게는 전용 좌석, 상태 표시등 및 명찰이 있습니다. 확인이 필요할 때는 빨간색 명찰과 느낌표로 알려줍니다.
  • 읽기 전용 터미널 화면: 직원을 클릭하면 최근 터미널 출력을 확인할 수 있지만, 사무실 인터페이스에서 명령을 전송할 수는 없습니다.
  • 게시판: 연간 목표, KPI, 이번 주 중점 사항, 현금 흐름 및 할 일 목록을 표시하며, 할 일은 직접 체크할 수 있습니다.
  • 책장 프로젝트 데이터베이스: 각 책은 하나의 프로젝트 폴더에 대응하며 Markdown 문서와 스크린샷을 읽을 수 있습니다.
  • 작업 목록: 오른쪽에서 작업 폴더의 파일과 전체 내용을 확인할 수 있습니다.
  • Minecraft 휴식 활동: 유휴 직원은 각자의 Mineflayer 봇으로 채굴, 나무 베기 및 집 짓기를 할 수 있으며, 사무실 책상 화면에는 1인칭 시점이 표시됩니다.

게시판 홈: 현금 흐름 및 연간 목표

게시판을 클릭하면 회사 데이터와 할 일을 확인할 수 있는 전체 화면 인터페이스가 열립니다.

책장: 프로젝트 데이터베이스

책장에서는 읽기 전용으로 프로젝트를 탐색할 수 있어 문서와 프로젝트 자료를 빠르게 확인하기에 적합합니다.

환경 요구 사항

  • Node.js 20 이상: 사무실 실행에 필요한 조건입니다.
  • Java 21 이상: Minecraft 기능을 활성화할 때만 필요합니다.
  • WebGL을 지원하는 브라우저: Chrome, Edge, Safari 및 Firefox를 사용할 수 있습니다.

macOS와 Linux가 주요 지원 플랫폼입니다. Windows는 현재 실험적으로 지원됩니다. CI에서는 설치, 구문 검사 및 데모 모드 테스트를 실행하지만, 작성자가 실제 Windows 환경에서 검증하지 않았으며 Minecraft도 아직 Windows에서 테스트되지 않았습니다.

데모 사무실 설치 및 시작

macOS 및 Linux

git clone https://github.com/jefferysha0627/agent-office-3d.git agent-office-3d
cd agent-office-3d
npm ci
npm start

Windows PowerShell

git clone https://github.com/jefferysha0627/agent-office-3d.git agent-office-3d
cd agent-office-3d
npm ci
npm start

시작하면 프로그램이 http://127.0.0.1:4870/을 엽니다. 기본값은 demo 모드이며 직원 상태가 자동으로 순환하므로 Agent를 미리 준비하거나 연결할 필요가 없습니다. 체험을 마친 후 터미널에서 Ctrl+C를 누르면 종료할 수 있습니다.

AI Coding Agent로 설치

Claude Code, Codex 또는 Cursor와 같은 AI Coding Agent를 사용하는 경우 프로젝트 폴더에서 먼저 실행한 뒤 다음 명령을 붙여 넣을 수도 있습니다.

이 repo의 AGENTS.md를 읽고 Agent Office를 설치한 다음 Minecraft 데모를 실행해 줘.

Agent는 AGENTS.md에 따라 npm run doctor를 실행하고, 데모 설치 및 시작을 지원하며, Herdr를 연결할지와 회사 및 직원을 어떻게 맞춤 설정할지 질문합니다. Node.js나 Java 같은 시스템 소프트웨어를 설치하기 전에는 먼저 확인을 요청합니다. Minecraft EULA는 반드시 사용자가 직접 읽고 yes를 입력해야 하며, AI Agent가 대신 동의할 수는 없습니다. Claude Code 사용자는 /setup-office를 입력할 수도 있습니다.

회사, 직원 및 데이터 소스 설정

먼저 예시 설정 파일을 복사합니다.

cp office.config.example.json office.config.json

Windows PowerShell에서는 다음을 사용할 수 있습니다.

Copy-Item office.config.example.json office.config.json

office.config.json은 버전 관리에 포함되지 않습니다. 파일이 없으면 프로그램이 예시 설정을 직접 사용합니다. 자주 사용하는 필드는 다음과 같습니다.

  • port: 서비스 포트이며 기본값은 4870입니다.
  • openBrowser: 시작 후 브라우저를 자동으로 열지 여부입니다.
  • company.name: 제목 표시줄과 회사 간판에 사용할 이름입니다.
  • company.currency: 게시판에 표시할 통화 기호입니다. 예: $ 또는 NT$.
  • company.logo 및 company.mark: 회사 가로형 Logo와 아이콘의 경로입니다.
  • owner.name, owner.title: 관리자 책상 인물의 이름과 직함입니다. 관리자 책상은 장식일 뿐 Agent 상태를 수신하지 않습니다.
  • cat.name: 사무실 고양이의 이름입니다.
  • staff[]: 직원 목록으로, id, title 및 유니폼 color를 포함하며 최대 8명까지 설정할 수 있습니다.
  • source.type: 상태 소스이며 demo 또는 herdr로 설정할 수 있습니다.
  • data.board, data.projects, data.tasks: 게시판, 프로젝트 및 작업 데이터의 위치입니다.

직원의 staff[].id는 상태 소스의 Agent 이름과 일치해야 합니다. 게시판 및 책장 데이터 형식은 docs/board-format.md를 참고할 수 있습니다.

실제 Agent 연결: Herdr 모드

Herdr는 Coding Agent용 터미널 멀티플렉서입니다. Herdr를 연결하려면 먼저 Herdr로 Agent를 시작한 다음 설정을 변경합니다.

{
  "source": {
    "type": "herdr"
  },
  "staff": [
    {
      "id": "사용자의 Herdr Agent 이름",
      "title": "직함",
      "color": "#4f8cff"
    }
  ]
}

그다음 실행합니다.

npm start

사무실은 Herdr의 읽기 전용 명령인 herdr agent list와 herdr agent read만 호출합니다. 내장 허용 목록이 다른 명령을 차단하므로 사무실이 대신 키 입력을 전송하거나 권한 확인을 승인하지 않습니다.

다른 상태 도구를 연결하려면 lib/sources.js에 adapter를 추가하여 이름, 상태 및 터미널 마지막 몇 줄의 출력을 포함한 동일한 형식의 직원 목록을 반환하도록 할 수 있습니다.

Minecraft 데모 활성화

데모 직원이 Minecraft를 플레이하는 모습을 빠르게 보고 싶다면 다음을 실행합니다.

npm run demo:minecraft

이 기능에는 Node.js 20 이상과 Java 21 이상이 필요합니다. 처음 실행하면 Java를 확인하고, Minecraft EULA를 읽고 수락하도록 요청하며, Mojang 공식 버전 목록에서 1.21.4 서버 파일을 다운로드하고 SHA-1을 검증합니다. 월드 생성에는 보통 약 1~2분이 걸립니다.

eula=true를 기록하려면 사용자가 직접 yes를 입력해야 합니다. 다른 내용을 입력하면 절차가 취소되며 Mojang 파일도 다운로드되지 않습니다. Minecraft 서버 소프트웨어의 EULA는 실제 실행자가 직접 동의해야 하기 때문입니다.

일반 사무실 모드에서 Minecraft를 활성화하려면 먼저 다음을 실행합니다.

npm run minecraft:setup

완료한 후 설정 파일의 minecraft.enabled를 true로 변경하고 npm start를 실행합니다. Minecraft 서버는 127.0.0.1에 바인딩되며 허용 목록으로 연결을 제한합니다. 직원이 업무를 재개하면 해당 봇은 활동을 멈춥니다. 직원이 유휴 상태이고 누군가 사무실 화면을 열어 둔 경우에만 봇이 작동합니다.

게시판 홈: 현금 흐름 및 연간 목표

Minecraft 게임 안에서 직원 보기

Minecraft Java Edition을 보유하고 있다면 자신의 플레이어 이름을 minecraft.guests에 추가할 수 있습니다.

{
  "minecraft": {
    "guests": ["YourName"]
  }
}

환경 변수를 사용할 수도 있습니다.

MC_GUESTS=YourName npm run demo:minecraft

Windows PowerShell에서는 다음을 사용할 수 있습니다.

$env:MC_GUESTS="YourName"; npm run demo:minecraft
  1. 같은 컴퓨터에서 Minecraft Java Edition 1.21.4를 엽니다.
  2. 멀티플레이어에 들어가 직접 연결을 선택한 다음 localhost:25570을 입력합니다.
  3. 접속하면 관전자 모드로 자동 전환되며, 월드를 변경하지 않고 비행하거나 벽을 통과할 수 있습니다.
  4. 숫자 키 1을 누르거나 마우스 가운데 버튼을 사용해 관전자 메뉴를 연 다음 직원을 선택하여 관찰합니다.

설정에 지정한 플레이어 이름은 봇과 함께 허용 목록에 추가되며, 다른 플레이어는 접속할 수 없습니다. 서버는 오프라인 모드로 실행되고 로컬 컴퓨터에서만 수신하므로 바인딩 주소를 변경하거나 외부에 공개해서는 안 됩니다.

개발 및 진단 명령

프로젝트에는 환경을 확인하고 변경 사항을 검증하는 데 적합한 몇 가지 명령이 제공됩니다.

npm run doctor  # 읽기 전용 환경 검사
npm run check   # JavaScript 구문 및 JSON 형식 검사
npm run smoke   # 데모 모드 스모크 테스트

npm run doctor는 모든 항목이 준비되었을 때 종료 코드 0을 반환하고, Minecraft가 아직 준비되지 않았을 때 2를 반환하며, 사무실을 실행할 수 없을 때 1을 반환합니다. -- --json을 추가하면 JSON 형식의 결과를 출력할 수 있습니다.

개발 중에는 URL 매개변수도 사용할 수 있습니다. 예를 들어 ?fast는 동작을 빠르게 하고, ?idle=coffee는 유휴 직원이 지정된 동작을 수행하게 하며, ?cat=nap은 고양이의 일정을 조정합니다. 사용할 수 있는 동작 이름은 public/behavior.js를 참조하세요.

안전 주의사항

  • 사무실은 Agent의 터미널 출력을 읽으며, 여기에는 코드, 경로 또는 민감한 정보가 포함될 수 있습니다.
  • 서버는 127.0.0.1에만 바인딩되고 Host 헤더를 확인합니다. 역방향 프록시, 터널 또는 공개 네트워크를 통해 서비스를 노출하지 마세요.
  • 사무실에서 유일하게 쓰기가 가능한 기능은 게시판의 할 일 항목을 체크하는 것입니다. 그 외의 Agent 상태와 터미널 데이터는 모두 읽기 전용입니다.
  • 책장은 설정된 폴더만 읽으며, 경로 순회와 디렉터리 밖으로 나가는 심볼릭 링크를 방지합니다. 그래도 프로젝트 폴더에 비밀번호나 토큰을 저장하는 것은 권장하지 않습니다.
  • Minecraft 서버는 로컬 호스트에서만 수신 대기하고 화이트리스트를 활성화합니다. 외부 연결이 가능하도록 변경하지 마세요.

맺음말

Agent Office 3D는 원래 터미널에 분산되어 있던 Agent 상태를 이해하기 쉬운 3D 사무실로 변환합니다. 먼저 npm start로 데모 모드를 체험한 다음, office.config.json을 통해 회사와 직원을 맞춤 설정하고, 마지막으로 Herdr에 연결하여 실제 Agent 상태를 확인할 수 있습니다. 상호작용을 더 추가하려면 npm run demo:minecraft를 사용해 유휴 직원이 로컬 Minecraft 월드에서 활동하는 모습을 볼 수 있습니다.

이 프로젝트는 MIT License에 따라 배포되며 Mojang 또는 Microsoft와는 관련이 없습니다. Minecraft를 사용할 때는 해당 EULA를 직접 읽고 동의해야 한다는 점을 기억하세요.