🤓 Terminal-Bench-RL: 강화학습 (Reinforcement Learning, RL)을 이용한 장기적 관점의 터미널 에이전트 학습

요약 (TL;DR):

• 장기적 관점의 터미널 기반 코딩 에이전트를 학습시키기 위해, 4개의 베어메탈 (bare metal) 노드에 걸쳐 32개의 H100 GPU까지 확장 가능한 안정적인 RL 학습 인프라를 성공적으로 구축했습니다.
• 이 과정에서 Terminal-Agent-Qwen3-32b를 개발하였으며, 이는 별도의 학습 없이도 terminal-bench에서 가장 높은 점수를 기록한 Qwen3 에이전트가 되었습니다!
  • 안타깝게도 저는 SOTA 코딩 에이전트를 학습시키기에는 GPU 자원이 너무 부족합니다 😅 (계산 비용으로 약 £30k-£50k 필요 예상). 하지만 만약 GPU를 보유하고 계신 분이 있다면, 이 프로젝트가 목표 달성을 도와줄 것입니다!

이 프로젝트는 UC Berkeley Sky Lab에서 개발한 rLLM 프레임워크를 기반으로 하며, 터미널 기반 에이전트 학습을 위해 특별히 설계된 커스텀 환경 및 인프라로 확장되었습니다.

📚 목차

• 💻💰 100만 달러 상당의 컴퓨팅 자원을 활용한 학습

  • 기타 학습 실행 (Other training runs)

• 🏆 Terminal Bench 리더보드 진입

  • 🏗️ 액션 기반 아키텍처 (Action-Based Architecture)

• 학습 세부 사항 (Training details)

  • ⚖️ 보상 설계 (Reward Design)
  • ✅ 정답 검증 (Answer Verification, 가중치 65%)
  • 🤖 LLM-as-a-Judge (가중치 35%)
    • 🧪 판사 평가 시스템 (Judge Evaluation System)
    • 🔄 동적 LLM 판사 전환 (Dynamic LLM Judge Switching)

• 🏗️ rLLM 통합 아키텍처 (rLLM Integration Architecture)

  • 터미널 에이전트 (TerminalBenchAgent)
  • Docker 환경 (DockerIsolatedEnv)

• 🔄 학습 및 롤아웃 세부 사항 (Training & Rollout Details)

  • 🔁 롤아웃 전략 (Rollout Strategy)
  • ⚙️ 학습 설정 프리셋 (Training Configuration Presets)

• 📊 주요 하이퍼파라미터 (Key Hyperparameters) (Production Config)

• 🗂️ 데이터셋 상세 정보 (Dataset Details)

  • 📊 데이터셋 구조 (Dataset Structure)
  • 🐳 훈련 환경 생성 (Training Environment Creation)
  • 🧹 Docker 리소스 관리 (Docker Resource Management)
  • 📂 데이터셋 준비 파이프라인 (Dataset Preparation Pipeline)

• 🚀 시작하기 (Getting Started)

  • 개발 환경 설정 (Development Setup)
  • Terminal Bench 평가 재현 (Terminal Bench Evaluation Reproduction)
  • 훈련 배포 (Training Deployment)
    • 단일 노드 훈련 (Single Node Training)
    • 멀티 노드 훈련 (Multi-Node Training)

• 🔮 향후 개선 사항 (Future Improvements)

  • 🚀 전체 훈련 실행 (Full Training Run)
  • 🤓 커리큘럼 학습 (Curriculum learning)
  • 📊 데이터셋 확장 (Dataset Expansion)
  • 🎯 스마트 데이터 필터링 (Smart Data Filtering)

• 감사의 글 (Acknowledgements)

💻💰 100만 달러 상당의 컴퓨팅 자원을 이용한 훈련

이 이미지는 4개의 베어메탈 (bare metal) 노드 클러스터에 분산된 32개의 H100에서 Qwen3-32B를 훈련시키며, 제 훈련 코드가 풀 스로틀 (full throttle)로 실행되는 모습을 보여줍니다. 이렇게 간소화된 경험을 제공해 준 Hyperbolic에 감사드립니다! 정말 즐거웠습니다!

이 정도 수준의 컴퓨팅 비용은 매우 막대하기 때문에, 영원히 실행할 수는 없었습니다! 그래서 코드가 제대로 작동하는지 확인했으며, 덜 사치스럽지 않은 하드웨어 설정에서도 코드를 실행해 보았습니다.

기타 훈련 실행 사례

또한 16개의 H100을 갖춘 2개의 베어메탈 (bare metal) 노드 클러스터에서 Qwen3-32B 훈련을 더 오래 실행했습니다:

또한 8개의 H100을 갖춘 1개의 VM 인스턴스에서도 실행했습니다:

가장 길게 진행한 훈련 실행은 단일 VM 인스턴스에서 2개의 A100을 사용하여 Qwen3-8B를 60 스텝 (steps) 이상 훈련시킨 것이었습니다:

참고: 8B 모델이 데이터셋의 과업을 해결하는 데 필요한 복잡한 행동을 학습하기 시작할 것이라고는 예상하지 못했습니다. 하지만 데이터셋을 통해 훈련을 진행하며 코드가 안정적인지 확인하는 과정은 매우 유익했습니다.

🏆 Terminal Bench 리더보드에 자리 잡기

Terminal bench는 에이전트가 터미널에서 복잡한 작업을 완료하는 능력을 정량화하기 위해 Stanford와 Laude Institute가 만든 훌륭한 벤치마크입니다.

프롬프트 엔지니어링 (Prompt engineering) 및 맞춤형 도구 설계를 통해, 저의 Qwen3-32B 에이전트는 Stanford의 Terminus-Qwen3-235B-30A MoE 에이전트는 물론, Deepseek R1 및 OpenAI의 GPT-4.1 Codex 에이전트보다 뛰어난 성능을 보이며 리더보드에서 가장 높은 점수를 기록한 Qwen3 에이전트가 되었습니다.

평가 실행에 대한 results.json 파일은 여기에서 확인할 수 있습니다.

훈련을 위한 컴퓨팅 예산 (Compute budget)이 뒷받침된다면, 제 에이전트가 리더보드 순위를 훨씬 더 높게 끌어올릴 수 있을 것이라 확신합니다.

에이전트 상세 정보

이 프로젝트 전체의 동기는 강화학습 (RL)을 사용하여 정교한 LLM 에이전트를 훈련함으로써 Terminal Bench 리더보드에 이름을 올리는 것이었습니다. 이를 위해 유능한 AI 에이전트가 복잡한 터미널/코딩 작업을 완료하는 데 사용할 수 있는 도구들(Claude Code에서 영감을 받음)과, 에이전트가 해당 도구들을 사용하고 특정 방식으로 작업에 접근하도록 유도하는 시스템 메시지를 개발했습니다.

이 도구들은 여기에서 확인할 수 있으며 다음을 포함합니다:

• 📝 할 일 관리 (Todo Management): 작업 진행 상황 계획 및 추적
• 📁 파일 작업 (File Operations): 파일 읽기, 쓰기 및 편집
• 🔍 검색 도구 (Search Tools): 파일 탐색을 위한 Grep, glob, ls
• ⚡ Bash 실행 (Bash Execution): 출력 캡처를 포함한 터미널 명령 실행
• 🗒️ 스크래치패드 (Scratchpad): 메모를 위한 공간
• 👍 작업 완료 (Task Completion): 에이전트가 작업이 완료되었다고 판단할 때 신호 전달

참고: 기술적으로 에이전트는 bash 도구에만 접근할 수 있어도 위의 모든 도구와 동일한 능력을 가질 수 있습니다. 이를 통해 개발 시간과 유지보수를 절약할 수 있습니다. 하지만 특정 도구에 명확한 API를 제공함으로써, 에이전트가 도구를 훨씬 더 효과적으로 이해하고 활용할 수 있게 합니다.

🏗️ 액션 기반 아키텍처 (Action-Based Architecture)

에이전트는 신뢰할 수 있는 파싱 (Parsing) 및 실행을 보장하는 구조화된 XML/YAML 형식을 통해 통신합니다:

<todo>
operations:
  - action: add
...

<bash>
cmd: 'find . -name "*.py" -path "*/test*" | head -10'
timeout_secs: 30
...

이 아키텍처는 다음과 같은 이점을 제공합니다:

• 타입 안정성 (Type Safety): 각 액션 (bash, file, search, todo)은 검증 기능을 갖춘 전용 핸들러 (Handler)를 가집니다.
• 오류 복구 (Error Recovery): 잘못된 형식의 YAML은 에이전트가 구문을 수정할 수 있도록 안내하는 유용한 오류 메시지를 트리거합니다.
• 순차적 실행 (Sequential Execution): 액션은 필수적인 중단 후 대기 (Stop-and-wait) 동작과 함께 한 번에 하나씩 처리됩니다.
• 일관된 피드백 (Consistent Feedback): 모든 액션은 에이전트가 학습하고 계획을 조정할 수 있는 구조화된 결과를 반환합니다.

이러한 도구들을 개발하는 것 외에도, 저는 다음과 같은 모범 사례를 권장하는 시스템 프롬프트 (System Prompt)를 작성했습니다:

• 구조화된 작업 실행 (Structured Task Execution): 명확한 문제 접근 단계 (계획 (Planning) → 탐색 (Exploration) → 실행 (Execution) → 검증 (Verification))
• 다회차 상호작용 (Multi-Turn Interaction): 적절한 중단 후 대기 동작을 포함한 액션-환경 사이클
• 필수 할 일 관리 (Mandatory Todo Management): 필수적인 초기 계획 및 지속적인 작업 추적
• 읽기 전용 탐색 (Read-Only Exploration): 어떠한 변경을 가하기 전에 정보를 먼저 수집

이 시스템 메시지 및 도구 조합과 유능한 LLM (저는 Qwen3-32B를 선택했습니다)을 결합하여, 저는 터미널 벤치 (Terminal Bench) 리더보드(현재 제출 중)에서 13.75%의 점수로 19위를 차지할 수 있었습니다. 이는 다음 모델들을 능가한 성적입니다:

• Stanford의 Qwen3-235B를 사용한 Terminus 에이전트
• Stanford의 Deepseek-R1을 사용한 Terminus 에이전트
• OpenAI의 GPT-4.1을 사용한 Codex 에이전트
• OpenAI의 codex-mini를 사용한 Codex 에이전트

에이전트는 여기에서 확인할 수 있습니다.

만약 제가 제대로 된 RL 실행을 위한 컴퓨팅 비용을 감당할 수 있다면, Qwen3-32B가 리더보드에서 어디까지 올라갈 수 있을지 정말 기대됩니다!

훈련 세부 사항 (Training details)

훈련 세부 사항 (Training details)

앞서 언급했듯이, 장기적 관점의 터미널/코딩 (terminal/coding) 작업을 위해 32B LLM을 전체 훈련하는 데 드는 컴퓨팅 비용은 제가 감당할 수 있는 수준이 아닙니다. 하지만 훈련 코드와 데이터셋은 준비되어 있으며, 2x A100부터 32x H100에 이르는 하드웨어 구성에서 안정적으로 훈련될 수 있음을 테스트했습니다.

⚖️ 보상 설계 (Reward Design)

강화학습 (RL) 과정에서 의미 있는 감독 (supervision)을 제공하기 위해, 두 가지 상호 보완적인 방법을 사용하여 보상을 계산했습니다.

✅ 정답 검증 (Answer Verification) (가중치 65%)

• 각 훈련 데이터 포인트에는 작업 완료를 검증하기 위한 Python 단위 테스트 (unit tests)가 포함되었습니다.
• 세부적인 부분 점수를 부여하기 위해 각 테스트에 개별 가중치를 할당했습니다.
• 테스트 실행은 에이전트가 작업을 수행한 격리된 Docker 컨테이너 내에서 실행되었습니다.
• 가중치 적용 점수 산정: 통과한 테스트는 최종 테스트 점수에 해당 가중치만큼 기여합니다.

🤖 LLM-as-a-Judge (가중치 35%)

• 에이전트의 행동을 평가하기 위해 외부 판사로 Claude-4-Sonnet을 사용했습니다.
• 다음 네 가지 주요 구성 요소를 평가했습니다:
  • 액션 출력 성공 (Action Output Success) (35%): 유효한 XML 액션, 성공적인 파싱 (parsing), 오류 복구 (error recovery)
  • 할 일 목록 사용 및 계획 (Todo Usage & Planning) (25%): 초기 계획, 작업 추적, 지속적인 업데이트
  • 단계 준수 (Phase Adherence) (25%): 5단계 워크플로 (Planning → Exploration → Refinement → Execution → Verification) 준수
  • 도구 사용 효율성 (Tool Usage Effectiveness) (15%): 적절한 도구 선택, 목적이 분명한 액션
• 오류 복구, 발견 품질, 효율성에 대한 품질 수정치 (quality modifiers)를 적용했습니다.
• 행동 없는 과도한 생각 (overthinking), 게임을 하는 듯한 행동 (gaming behaviors), 단계 위반에 대해 페널티를 부여했습니다.
• 작업이 완료되었는지 여부(WHETHER)가 아니라, 에이전트가 어떻게(HOW) 작업했는지를 기준으로 점수를 매겼습니다.

🧪 판사 평가 시스템 (Judge Evaluation System)

강화학습 (RL) 훈련 과정에서 LLM 판사 (LLM judge)가 정확하고 일관된 점수를 제공하는지 보장하기 위해, 저는 간단한 평가 시스템을 개발했습니다:

• 서로 다른 에이전트 궤적 (trajectories)을 보여주는 테스트 케이스 생성
• 점수 산정의 정확도를 비교하기 위해 Kimi K2, Qwen-3-Coder, Claude Sonnet 4, Claude Haiku 3.5를 포함한 여러 LLM 모델을 판사로 테스트
• Claude Sonnet 4가 탐색 부족(lack of exploration)이나 과도한 생각(overthinking)과 같은 문제들을 정확히 식별하며 가장 일관되고 정확한 점수를 제공한다는 것을 발견
  • 불행히도 Sonnet-4는 비용이 매우 비싸서, 32번의 롤아웃 (rollout)과 1650 스텝 (step)의 실행을 감당하기에는 경제적이지 않습니다! 하지만 좋은 궤적과 나쁜 궤적을 충분히 잘 구분하는 유일한 모델이었습니다.
  • 다른 많은 모델들(Haiku 3.5 포함)은 문제가 있는 에이전트의 행동에 대해 부풀려진 점수를 주었으며, 일부는 중요한 단계를 건너뛴 에이전트에게 0.85-0.95의 점수를 주기도 했습니다.

판사 모델의 성능을 분석하려면:

# 특정 모델에 대해 평가 실행
uv run python evaluation/llm_as_a_judge_evals/judge_eval.py --model openrouter/openai/gpt-4.1 --attempts 3

...

상위 5개 판사 모델 성능:

Claude Sonnet 4는 Haiku와 동일한 통과율을 가졌음에도 불구하고 1위를 차지했는데, 이는 현저히 낮은 평균 점수(0.26 대 0.70)가 더 엄격하고 정확한 판정(평가 데이터셋 기준)을 내리고 있음을 나타내기 때문입니다. 점수가 낮다는 것은 해당 모델이 다른 판사들이 놓치는 문제적인 에이전트 행동을 더 잘 식별한다는 것을 의미합니다.

테스트된 다른 모델로는 GPT-4.1, Gemma-3-27B-IT, Qwen3-32B, 그리고 Qwen3-235B-A22B가 있습니다.

🔄 동적 LLM 판사 전환 (Dynamic LLM Judge Switching)

장기적인 학습 과정 중 모델 과부하, 토큰 제한 또는 성능 요구 사항을 처리하기 위해, 인프라는 서로 다른 LLM 판사 (LLM judge) 백엔드 간의 핫스왑 (hot-swapping)을 지원합니다:

• 학습 프로세스를 중단하지 않는 런타임 전환 (Runtime switching)
• 필요에 따라 Claude Code CLI와 LiteLLM 백엔드 간 전환
• API 토큰 제한 또는 예산 제약에 도달했을 때 유용함
• switch_judge_backend.py 및 전환 문서 참조

예시 워크플로우:

# Claude Code CLI로 시작
python training_scripts/launch_training.py prod_32b_8_gpus

...

🏗️ rLLM 통합 아키텍처 (rLLM Integration Architecture)

이 프로젝트는 rLLM의 BaseAgent 및 BaseEnv 인터페이스를 확장하여 완전한 강화학습 (RL) 학습 루프를 생성합니다:

터미널 에이전트 (TerminalBenchAgent)

• 환경 (environment)과 LLM 사이의 다회차 대화 (multi-turn conversations)를 관리하기 위해 rLLM의 BaseAgent를 확장함
• 시스템 프롬프트 (system prompt), 사용자 지시 사항 (user instructions), 에이전트 응답 (agent responses)을 포함한 대화 기록을 유지함
• GRPO 학습을 위해 관측 (observations), 행동 (actions), 보상 (rewards)이 포함된 전체 궤적 (trajectories)을 추적함