AI 에이전트 Unreal Agent 실전 사용법: 러너부터 검증까지

AI 에이전트 런타임 Unreal Agent란 무엇인가

Unreal Agent는 모델과 실제 작업을 수행하는 툴 사이를 잇는 계층입니다. 현장 감독에 비유하면 이해하기 쉽습니다. 모델이 해야 할 일을 판단하면 런타임은 명령을 배정하고, 실행 내역을 기록하며, 각 결과를 언제 모델에 전달할지 결정합니다.

가장 두드러지는 설계는 비동기 툴 실행입니다. 모델이 툴을 호출하면 런타임은 작업이 진행 중임을 기록하고 백그라운드에서 계속 실행되도록 둡니다. 작업이 끝나면 최종 결과를 세션에 추가하고 모델을 다시 호출합니다. 따라서 설정 명령 하나가 오래 걸리더라도 다른 유용한 작업이나 새로 들어온 지시까지 막을 필요가 없습니다.

Unreal Labs는 2026년 9월 22일 이 프로젝트를 공개했습니다. SDK에는 Go 라이브러리, 설치형 러너, Harbor 호환 벤치마크 러너가 포함됩니다. 저장소에는 MIT License가 적용됩니다.

Unreal Labs는 자사 프로덕션 워크로드와 공개 에이전트 벤치마크에서 Codex보다 최대 40%, Pi보다 최대 20% 비용이 낮았다고 밝힙니다. 어디서나 그대로 적용되는 할인율이 아니라 공급사가 제시한 결과로 보아야 합니다. 그래도 검증할 만한 작동 원리는 분명합니다. 프롬프트가 작고 툴 결과가 간결하며, 서브 에이전트나 워크플로가 없고, 모델 호출 사이에 더 많은 툴 작업을 처리한다는 설명입니다. 모델, 추론 수준, 프롬프트, 저장소 상태, 성공 기준을 동일하게 맞추기 전에는 이 비율 자체에 의미가 없습니다.

비용 계산은 벤치마크가 아니라 작업에서 시작합니다

러너는 MIT License에 따라 사용자당 라이선스 요금이 없지만, 운영비까지 사라지는 것은 아닙니다. 모델 호출, 컴퓨팅, 샌드박스, 통합, 로그, 그리고 시스템을 안정적으로 유지할 엔지니어 비용은 여전히 발생합니다.

비교할 수 있는 예산은 코드 리뷰 서비스 가격에서 확인할 수 있습니다. Graphite는 연간 결제 기준 Starter를 사용자당 월 $20, Team을 월 $40에 제공합니다. CodeRabbit의 연간 결제 요금은 개발자당 월 $24, $48, $72입니다. 개발자 10명으로 구성된 팀이라면 공개된 가격 범위는 매달 $200~$720입니다.

그렇다고 Unreal Agent가 두 제품을 곧바로 대체할 수 있다는 뜻은 아닙니다. 다만 플랫폼 팀이 범위가 좁은 내부 워크플로 하나를 구축할 출발점이 되는 오픈 런타임입니다. 경제성을 따지는 방법은 단순합니다. 모델 비용과 유지보수를 포함한 해당 워크플로의 월간 총비용을, 대체할 사용자당 예산이나 엔지니어링 시간과 비교하면 됩니다. 완료된 작업의 비용을 측정할 수 없다면 비용 절감 주장은 장식에 불과합니다.

범위를 제한한 저장소 작업 실행 방법

먼저 러너를 사용하십시오. 라이브러리는 어떤 에이전트 동작을 애플리케이션 안에 넣을지 이미 판단한 팀을 위한 선택지입니다.

1. 저장소에 실질적인 경계를 설정합니다

-workspace는 에이전트와 Bash 툴이 사용할 작업 디렉터리를 지정합니다. 보안 샌드박스로 문서화된 기능은 아닙니다. 폐기 가능한 체크아웃이나 컨테이너를 사용하고, 프로덕션 자격 증명을 제거하며, 네트워크 접근을 제한하고, 프로세스에는 꼭 필요한 토큰만 제공하십시오. 프롬프트에 “파일을 수정하지 마십시오”라고 적는 것은 지시일 뿐 강제 장치가 아닙니다. 처음 구축하는 환경이라면 AI 에이전트 코드 샌드박스의 실용적인 선택지부터 살펴보는 편이 좋습니다.

워크스페이스에 .env 파일이 있는지도 확인하십시오. 러너는 선택한 워크스페이스에서 이 파일을 불러오므로, 복사한 저장소에도 미처 제거하지 못한 자격 증명이 남아 있을 수 있습니다.

2. 러너·공급사·모델·추론 수준을 고정합니다

2026년 9월 24일 기준 최신 릴리스는 하루 전에 공개된 v0.2.0입니다. 러너 README는 Go 1.27 이상을 요구하고 @latest 사용법을 안내하지만, 재현 가능한 평가를 위해서는 릴리스 태그를 사용해야 합니다.

아래 실행 예시는 OpenAI, 현재 소스의 기본값인 gpt-6-astra, high 추론 수준을 사용합니다. 다른 모델로 바꾼다면 반드시 어떤 모델을 썼는지 기록하십시오. my-project의 폐기 가능한 복사본을 대상으로 다음 명령을 실행합니다.

go version
go install github.com/unreallabsai/unreal-agent/cmd/unreal-agent-runner@v0.2.0

export OPENAI_API_KEY="..."
export UNREAL_HARNESS_LLM_PROVIDER="openai"
export UNREAL_HARNESS_LLM_MODEL="gpt-6-astra"

started_at=$(date +%s)
set +e
unreal-agent-runner \
  -workspace ./my-project \
  -session-directory ./unreal-sessions \
  '{"prompt":"Read this repository. Return its purpose, entry points, test command, and three concrete risks. Do not modify files.","model":"gpt-6-astra","thinking_level":"high","session_id":"repo-summary-v1","disallowed_tools":["ViewImage"]}' \
  > run.jsonl
run_status=$?
set -e
elapsed_seconds=$(( $(date +%s) - started_at ))
printf 'exit_status=%s elapsed_seconds=%s\n' "$run_status" "$elapsed_seconds"
jq -c 'select(.Kind=="model_response") | .Data.Response.Usage' run.jsonl

러너는 openai-codex, openrouter, fireworks, ollama도 지원합니다. 요청에서 모델, 추론 수준, 재시도 횟수, 세션 ID, 시스템 프롬프트, 제외할 툴을 선택할 수 있습니다. 현재 extra_allowed_tools 필드는 입력으로 받지만 무시되므로 임의의 툴을 추가할 수는 없습니다.

3. 실행 기록을 근거로 읽습니다

제대로 된 평가 기록에는 다음 여섯 가지가 필요합니다.

저장된 세션은 unreal-sessions/repo-summary-v1.session.jsonl입니다. 같은 세션을 이어가려면 동일한 session_id를 다시 사용하십시오. 깨끗한 조건에서 비교하려면 새 ID를 써야 합니다. 그렇지 않으면 이전 컨텍스트 때문에 품질과 비용이 모두 달라질 수 있습니다.

실제 공급사로 실행을 완료하지 않았으므로 이 글에서는 직접 측정한 성능 결과를 주장하지 않습니다. 정직하게 제시할 수 있는 성능 수치는 자체 저장소에서 직접 확보한 값뿐입니다.

러너와 라이브러리 중 무엇을 선택해야 하는가

프롬프트를 시험하거나, 저장소 작업을 평가하거나, 프로세스를 CI에 연결할 때는 러너를 선택하십시오. 에이전트를 제품 안에 넣어야 하고 세션 저장, 수명주기 동작, 툴, 보안, 공급사 통합을 직접 책임질 준비가 됐다면 Go 라이브러리가 맞습니다.

전동 공구와 그 안의 모터를 떠올리면 차이가 선명합니다. 러너는 스위치까지 달려 바로 쓸 수 있는 공구이고, 라이브러리는 외장과 조작부, 안전장치를 자유롭게 설계할 수 있는 모터입니다. 세션 소유권이 선택의 핵심이라면 Agents API와 SDK 비교도 인접한 판단 기준으로 참고할 수 있습니다.

통합 작업은 과제 자체의 약점을 가릴 수 있으므로 기본 선택은 러너가 되어야 합니다. 범위가 같은 프롬프트로 두 번 실행해도 유용한 결과를 내지 못한다면 API 래퍼를 더한다고 제품 아이디어가 나아지지는 않습니다.

우선순위로 정리한, 테스트할 만한 작업 여섯 가지

1. 에이전트가 작성한 풀 리퀘스트의 초벌 리뷰

대규모 AI 생성 풀 리퀘스트를 받는 엔지니어링 팀이라면 러너에 깨끗한 체크아웃, diff, 저장소 테스트 명령을 제공할 수 있습니다. 러너는 영향받은 코드를 살피고, 관련 검사를 실행하며, JSONL 근거가 딸린 리뷰 패킷을 반환합니다. 목적은 사람의 리뷰를 없애는 데 있지 않습니다. 반복적인 저장소 점검을 먼저 끝내 리뷰어가 아키텍처와 위험에 집중하도록 만드는 데 있습니다.

2. 새 엔지니어를 위한 저장소 안내

플랫폼 팀은 새 엔지니어가 서비스에 합류할 때마다 앞서 제시한 요약 프롬프트를 그대로 실행할 수 있습니다. 결과에는 진입점, 테스트 명령, 설정, 눈에 띄는 위험이 정리되고, 검증할 수 있도록 세션 추적 기록도 남습니다. 시니어 엔지니어가 같은 저장소를 매번 처음부터 설명하지 않아도 일관된 첫 한 시간을 제공할 수 있다는 것이 효과입니다.

3. 실패한 테스트 분류

CI 실패 로그가 복잡할 때 개발자는 러너에 실패한 테스트 하나를 재현하고, 관련 코드 경로를 검색하며, 가능성이 큰 원인과 무관한 출력을 구분해 달라고 요청할 수 있습니다. 환경 설정과 검색, 테스트 실행이 겹쳐 진행될 수 있어 비동기 툴 처리가 특히 유용한 작업입니다. 실제 수정을 담당할 엔지니어에게 더 작은 근거 패킷을 건넬 수 있습니다.

4. 의존성 업그레이드 준비

유지관리자는 의존성 하나를 올린 브랜치를 에이전트에 제공하고, 영향을 받는 import, 폐기 예정 호출, 테스트 커버리지, 마이그레이션 메모를 요청할 수 있습니다. 결과물은 자동 병합이 아니라 체크리스트가 됩니다. 엔지니어링 시간을 통째로 투입하기 전에 범위를 더 빨리 파악할 수 있습니다.

5. 릴리스 준비 상태 점검

릴리스 담당자는 릴리스 후보에서 변경된 영역, 빠진 마이그레이션, 문서 공백, 관련 테스트 명령을 찾아 달라고 요청할 수 있습니다. 세션 기록에는 에이전트가 실제로 무엇을 살폈는지가 남습니다. 결정론적 CI를 대체하지 않으면서 일관된 사전 점검을 더할 수 있습니다.

6. 지원 이관 패킷 작성

제품 엔지니어는 재현 가능한 고객 문제를 민감 정보를 제거한 저장소 환경에 넣고, 가능성이 있는 코드 경로를 추적하고 증상을 재현하며 미해결 질문을 나열하도록 러너에 요청할 수 있습니다. 에이전트에 고객 프로덕션 시스템 접근 권한을 주지 않고도 지원팀에서 엔지니어링팀으로 구조화된 인계를 만들 수 있습니다.

제품으로 만들 만한 아이디어 두 가지

가장 유망한 선택: AI 생성 코드용 리뷰 게이트

격리된 워크스페이스에서 Unreal Agent를 실행하고, 저장소 규칙에 따라 풀 리퀘스트를 검토하며, 허용된 검사를 수행하고, 사람 리뷰어에게 근거 링크가 포함된 요약을 게시하는 GitHub 또는 GitLab 검사를 구축할 수 있습니다. 에이전트로 더 많은 코드를 생산하는 팀이 구매자입니다.

수요는 분명합니다. ai powered code review platform은 미국에서 월간 약 1,900회 검색되며, ai code review는 약 1,300회 검색되고 CPC는 $55.73입니다. 기존 제품의 가격을 보면 연간 결제 기준 개발자당 월 $20~$72의 예산도 이미 검증되어 있습니다.

판매 가능한 최소 버전은 코드 호스트 하나, 모델 공급사 하나, 고정된 리뷰 프롬프트, 엄격한 명령 허용 목록, JSONL 추적 기록으로 만든 결과 페이지를 지원합니다. 관건은 신뢰입니다. 오탐, 비밀정보 유출, 불필요하게 많은 댓글, 안전하지 않은 명령은 가치를 순식간에 없앨 수 있습니다. 그래도 자주 발생하고 측정 가능하며 기존 예산과 연결된다는 점에서 가장 좋은 기회입니다.

모델을 직접 선택하는 저장소 작업 러너

팀이 저장소, 검증된 작업 템플릿, 공급사, 모델, 비용 한도를 선택하면 세션 추적 기록과 승인 가능한 결과를 받는 소규모 내부 컨트롤 플레인을 만들 수 있습니다. 오픈 런타임은 원하지만 큐, 격리, 보고 계층을 직접 만들고 싶지 않은 에이전시와 플랫폼 팀이라면 비용을 지불할 만합니다.

open source ai coding agent는 미국에서 월간 약 5,400회 검색되며 상업적 의도가 있고 CPC는 $13.11입니다. 리뷰 관련 검색어보다 수요는 넓지만, 제품에 대한 요구는 덜 구체적입니다.

MVP에는 저장소 커넥터, 임시 워크스페이스, 작업 템플릿 두 개, 공급사 설정, 작업 상태, 토큰 보고, 다운로드 가능한 JSONL이 필요합니다. 관건은 차별화입니다. 초기 런타임 위에 얇은 대시보드만 씌운 제품은 쉽게 복제할 수 있으며, 진지한 구매자는 신원 통제, 감사 로그, 네트워크 정책, 신뢰할 수 있는 정리 기능을 요구합니다. 제품 이름이 아니라 구체적인 워크플로와 운영 통제로 승부해야 합니다.

Unreal Agent가 해결하지 않는 문제

Unreal Agent가 완전한 프로덕션 경계를 제공하는 것은 아닙니다. 워크스페이스 플래그는 샌드박스가 아니며, 내장 Bash 툴은 주어진 환경 안에서 동작할 수 있습니다. 격리, 네트워크 정책, 자격 증명, 승인, 정리는 여전히 사용자의 책임입니다.

공급사 간 차이도 없애주지 않습니다. Unreal Labs는 테스트 과정에서 일부 비 OpenAI 추론 공급사의 일부 모델이 진행 중 결과와 최종 툴 결과를 함께 전달하는 패턴을 거부했다고 밝힙니다. 출시하려는 공급사와 모델 조합을 정확히 지정해 검증해야 합니다.

복잡한 오케스트레이션 기능도 제공하지 않습니다. 서브 에이전트나 워크플로를 두지 않은 가벼운 구조 자체가 효율성 주장의 일부입니다. 제품에 시각적 워크플로 빌더, 방대한 관리형 커넥터 카탈로그, 별도 설정 없이 바로 쓰는 전문가 에이전트 위임 기능이 필요하다면 적합하지 않습니다.

자체 워크로드에서도 비용이 줄어든다고 입증해 주지는 않습니다. 모델 선택, 추론 강도, 캐시 동작, 툴 출력, 재시도, 작업 성공 여부가 모두 비용을 바꿉니다. 설정이 다른 원시 토큰 합계가 아니라 성공적으로 완료된 작업끼리 비교하십시오.

월요일에 바로 할 일

월요일에는 플랫폼 엔지니어가 v0.2.0을 고정하고, 자격 증명이 없는 저장소 복사본 하나를 준비한 뒤, 같은 모델과 추론 수준으로 저장소 요약 작업을 두 번 실행해야 합니다. JSONL, 세션 파일, 종료 상태, 소요 시간, 토큰 사용량, 저장소 diff를 보관하십시오. 두 실행 모두 유용하고 깨끗하다면 현재 사용하는 에이전트로 같은 작업을 반복합니다. 그 결과를 확인한 뒤에야 리뷰 워크플로를 시험할지, 라이브러리를 내장할지 결정해야 합니다.

자체 워크플로에 맞춘 통제된 저장소 에이전트가 필요하다면 AI 에이전트 개발부터 시작하는 것이 좋습니다.