ApodexAI/FrontierAgent

FrontierAgent는 장기적인 연구 및 파일 기반 작업을 위한 오픈 소스 에이전트 런타임, 터미널 제품, 그리고 평가 스위트입니다. frontier-agent TUI는 두 가지 네이티브 워크플로우를 제공합니다:

ReAct: 하나의 상태 저장(stateful) 에이전트가 연구하고, 파일을 읽고, 결과물을 작성하며, 명령을 실행하고, 작업 범위 내의 샌드박스에서 반복 작업을 수행합니다. Agent Team: 코디네이터가 작업 보드를 유지하고, 독립적인 작업을 병렬 서브 에이전트에게 위임하며, 그들의 보고서를 수집하고, 결과를 종합합니다.

동일한 워크플로우 엔진은 Apodex 모델을 평가하는 데 사용되는 벤치마크 러너에 전력을 공급합니다. 프레임워크, 도구, 워크플로우, 그리고 평가 계층은 분리되어 있어 각각 독립적으로 재사용할 수 있습니다.

중요 사항

모델 호스팅 불필요. API 키를 받아 OpenAI와 호환되는 Apodex-1.1 엔드포인트에 연결한 후 몇 분 만에 FrontierAgent 실행을 시작하세요.

⏳ 이는 기간 한정 혜택입니다—직접 사용해보고 무엇을 만들 수 있는지 알려주세요!

처음이신가요? **문서 색인(documentation index)**을 사용하여 적절한 설치, SGLang, 워크플로우, 평가 또는 개발자 가이드를 찾으세요.

네이티브 Agent Team 워크플로우. 코디네이터는 요청을 분해하고, 제한된 병렬 할당을 전송하며, 구조화된 보고서를 받고, 최종 증거 검토를 위해 선택적 빠른 리포터(fast reporter)를 사용할 수 있습니다. 작업 보드(Task Board). Agent Team의 add_task와 update_task 이벤트는 대기 중, 활성, 완료됨, 차단됨, 취소된 상태로 TUI 사이드바에 실시간으로 나타납니다. 샌드박스 파일 작업. 셸 및 파일 도구들은 하나의 작업 범위(task-scoped) 파일 시스템을 공유합니다: /inputs는 읽기 전용(read-only)이며, /workspace가 작업 상태 공간이고, /outputs에는 영구적인 결과물이 포함됩니다. 권한 부여 및 샌드박스 실패 시에는 fail-closed 방식으로 작동합니다. 비동기 개입(Asynchronous intervention). 에이전트가 실행되는 동안 타이핑하여 새로운 명령을 예약할 수 있습니다. 이는 활성 실행을 폐기하지 않고 다음 안전한 턴 경계에서 주입됩니다. Agent Team 모드에서는 코디네이터를 안내하며, 이미 실행 중인 서브 에이전트는 완료되도록 허용됩니다. 투명한 결과물(Transparent deliverables). macOS/Docker의 경우, /outputs는 .apodex/runs/<session-id>/outputs에 매핑됩니다.

호스트에서. 동일한 실행 디렉터리에는 체크포인트(checkpoint), 트레이스(trace), 엔진 로그(engine log) 및 궤적(trajectories)도 포함됩니다.승인(Approval), 트레이스, 그리고 복구(recovery). 변형 작업은 diff를 보여주며, --yes가 활성화되지 않는 한 승인이 필요합니다. 세션은 체크포인트되며, 모든 액션은 로컬에서 트레이스되고, /revert는 세션 변경 사항을 복원하며, --resume는 저장된 실행을 계속합니다.평가 포함(Evaluation included). 서브프로세스 러너는 연구 및 파일 기반 벤치마크, 결정론적 아티팩트 수집, 동시성(concurrency), 진행 상황 검사(progress inspection) 및 개별 실패 재실행을 지원합니다.

작업 위임 및 비동기 보고서 수집부터 검증 및 최종 합성까지의 개념적 에이전트 팀 워크플로우.

flowchart LR
U["사용자 / 벤치마크 작업"] --> TUI["TUI 또는 서브프로세스 러너"]
TUI --> R["상태 저장 ReAct"]
...

저장소 경계는 의도적입니다:

frontier_agent/	일반 루프, 스케줄링, 레지스트리(registries), AgentBus, 옵저버(observers)
plugins/tools/	웹(web), 셸(shell), 파일(file), 샌드박스(sandbox) 및 팀 도구 구현
workflows/	ReAct 및 에이전트 팀 파이프라인, 프로필, 프롬프트, 옵저버
...

더 자세한 내용: 프레임워크 아키텍처, 에이전트 팀, 그리고 상태 저장 ReAct. 온디스크 레이아웃을 확인하려면 실행된 아티팩트와 타임스탬프를 참조하십시오.

요구 사항: Git, Python 3.12, uv, 그리고 OpenAI 호환 모델 엔드포인트. Docker는 선택 사항입니다.

git clone https://github.com/ApodexAI/FrontierAgent.git
cd FrontierAgent
uv sync --python 3.12 --extra dev
...

.env에 엔드포인트를 추가하십시오:

:

OPENAI_API_KEY=your-key
OPENAI_BASE_URL=https://your-openai-compatible-endpoint/v1
OPENAI_MODEL=your-model-name
...

SERPER_BASE_URL과 제공업체에서 발급한 SERPER_API_KEY를 설정하여 모든 Serper.dev 호환 엔드포인트(litescrape.com, serpbase.dev 등)를 지원합니다.

WEB_SEARCH_PROVIDER=parallel을 설정하여 무료이며 키가 필요 없는 Parallel Search MCP를 web_search에 사용하십시오.

. Serper가 기본값으로 유지되므로 기존 키 및 누락된 키 오류는 현재 동작을 유지합니다. 병렬 MCP는 도구의 사용자 지정 지역, 언어 또는 시간 필터, 또는 쿼리당 10개 이상의 카운트를 지원하지 않으므로, 해당 기능이 필요할 때는 Serper를 선택하십시오.
web_fetch
은 기존의 fetch provider를 계속 사용합니다.

TUI(Terminal User Interface) 시작:

# 상태 유지 싱글 에이전트 워크플로우
uv run frontier-agent --mode react --cwd /path/to/project
# 코디네이터 및 병렬 서브 에이전트
...

uv sync
은 경량 터미널 런타임을 설치합니다. 과학 및 문서 패키지는 네이티브 모드에서 의도적으로 선택 사항이며, 에이전트는 작업에 실제로 필요한 것만 <project>/.apodex/runtime/native에 설치합니다.

apodex 명령어는 호환성 별칭으로 유지됩니다.

frontier-agent를 다른 모든 명령줄 도구처럼 실행하려면, 이 리포지토리에서 uv로 설치하고 엔드포인트를 하나의 사용자 파일에 보관하십시오:

uv tool install --python 3.12 git+https://github.com/ApodexAI/FrontierAgent.git
# OPENAI_API_KEY, OPENAI_BASE_URL 및 OPENAI_MODEL을
# ${XDG_CONFIG_HOME:-$HOME/.config}/apodex/env에 넣고 chmod 600 처리합니다.
...

내보낸 변수와 프로젝트의 .env 파일이 여전히 사용자 파일을 우선합니다. Docker가 실행되는 macOS에서는 컨테이너 이미지를 클론으로부터 한 번 빌드해야 합니다. 한 번 설치하고 모든 프로젝트에서 실행하는 것은 PATH 설정, 우선순위 규칙, Docker 단계 및 업데이트를 포괄합니다.

모든 것을 처리하는 스크립트를 선호하십니까? ./scripts/run-macos.sh와 ./scripts/run-linux.sh은 호스팅된 엔드포인트 설치를 설정하고, ./scripts/run-linux-gpu.sh --install-system-deps --setup-only는 Linux NVIDIA GPU에 네이티브하고 격리된 SGLang 환경을 준비합니다. 단계별 동등물은 모델 자체 호스팅이나 Docker가 필요하지 않은 엔드포인트 퀵스타트(中文教程)입니다.

로컬 SGLang 서빙은 검토된 NVIDIA 드라이버/CUDA/SGLang 트랙에 고정되어 있으며, 불일치는 모델 로딩 중 불투명한 CUDA 또는 Triton 커널 오류로 인해 나중에 나타납니다. nvidia-smi를 확인하십시오.

이미지 태그나 네이티브 핀을 선택하기 전에 드라이버를 GPU 호환성 매트릭리에 맞게 조정합니다. GPU 헬퍼는 호스트 드라이버에서 검토된 사용자 공간 트랙을 선택하지만, 드라이버 자체를 설치하거나 교체하지는 않습니다.

운영 체제(OS), FrontierAgent 런타임, 모델 런타임은 독립적인 선택입니다. “NVIDIA”는 에이전트 자체가 실행되는 방식이 아니라 로컬 모델 서비스를 설명합니다. 자신의 장치나 GPU 공급업체에 어떤 것이 적용되는지 확실하지 않으신가요? **설치 선택기(installation chooser)**부터 시작하세요.

| 환경 | FrontierAgent 런타임 | 모델 엔드포인트 | 여기서 시작하기 | :--- | :--- | :--- | :--- | | macOS | 네이티브 또는 Docker Desktop | 호스팅 또는 다른 OpenAI 호환 엔드포인트 | macOS |
| ... |
중국어 사용자가 사용하는 macOS의 경우, macOS 中文安装与一键启动指南을 사용할 수 있습니다.

사전 구축된 linux/amd64 및 linux/arm64 이미지는 GitHub Container Registry에 게시되므로 로컬 Python 환경이 필요하지 않습니다. 해당 패키지는 비공개(private)이므로, docker login ghcr.io (계정이 승인되어 있어야 함)가 필요합니다. 그렇지 않다면 다음 체크아웃을 빌드하세요:

cp .env.example .env
docker compose -f compose.yaml -f compose.dev.yaml build
docker compose -f compose.yaml -f compose.dev.yaml run --rm agent

• Docker에서 FrontierAgent 실행 — Compose, 이미지 핀닝(image pinning), 직접 docker run, 그리고 EC2/ECS 배포.
• Linux NVIDIA 호스트의 Docker SGLang — 하나의 네트워크에 두 개의 컨테이너; SGLang이 GPU를 소유합니다.
• 중첩된 데몬을 금지하는 관리형 GPU 환경을 위한 네이티브 SGLang.
• SGLang 구성 참조 — 모든 .env.sglang 변수, 토큰 예산 불변량(token-budget invariants), 그리고 튜닝 순서.

RTX 4090, RTX 5090 및 두 개의 GPU 호스트용 프로덕션 35B 템플릿은 config/sglang/ 아래에 있습니다.

작업 없이 대화형 세션을 실행하거나, 작업을 전달하고 후속 조치를 위해 세션에 머무르세요:

uv run frontier-agent --mode agent_team --cwd /repo \
"Research the alternatives, verify the evidence, and write a report"
# 일회성(One-shot), 라인 모드 또는 저장된 세션 재개
...

사이드바에는 계획/작업 보드, 실시간 도구 활동, 결과물(deliverables), 세션별 diff가 표시됩니다. 워크플로우가 실행 중일 때 후속 내용을 입력하면 실행을 방해하는 대신 다음 안전한 턴 경계에 따라 대기열에 추가됩니다.

사이드바의 네 가지 탭, 미리 보기, 승인, 첨부 파일, 클립보드 지원,
키, 그리고 Agent Team 실시간 조향(live steering)에 대해서는
[TUI 사용자 가이드](링크 없음)
(중국어 사용 튜토리얼)를 참고하세요. 전체 슬래시 명령어, 옵션 및 테마 참조는 apodex/README.md에 있습니다.

Agent Team의 병렬성은 벤치마크 동시성(concurrency)에 추가됩니다. 평가를 시작할 때는 --concurrency 1부터 하세요.

; 총 동시 모델 호출 수는 러너 동시성(runner concurrency)에 팀 생성 제한을 곱한 값에 근접할 수 있습니다.

Agent Team 웹 도구를 비활성화하려면 SWARM_NO_WEB=1을, 폐쇄형 책(closed-book) ReAct 작업을 위해 REACT_NO_WEB=1을 설정하세요.

세션은 쓰기, 삭제, 패키지 설치 및 위험한 셸 명령어에 승인 게이트를 추가합니다. 일부 작업은 --yes 옵션을 사용하더라도 거부 상태로 유지되며; 파일 변형(file mutations)은 저널링되므로 /revert 명령으로 되돌릴 수 있습니다.

세부 사항: 샌드박싱 및 경로 정책, 승인 및 추적 동작, 보안 정책을 참조하세요.

uv sync --frozen --extra sandbox --extra document-readers --extra eval --extra dev
uv run pytest -q
uv run ruff check .

전체 개발 환경, 사전 점검(pre-flight checks), 세션 디버깅 및 제출 프로세스는 CONTRIBUTING.md를 참조하십시오. 컨테이너 이미지를 빌드하는 방법은 Run FrontierAgent in Docker에서 다룹니다.

평가 하네스(evaluation harness)는 각 벤치마크 질문을 격리된 서브프로세스(subprocess)에서 실행하며, 재개 가능한 다중 실행 실험(resumable multi-run experiments)을 지원하고, 벤치마크별 결정론적 또는 모델 기반 심사위원(judge)을 배포합니다. 데이터셋이 평가 가이드에 따라 다운로드된 후 최소한의 스모크 테스트(smoke run)는 다음과 같습니다:

uv sync --extra eval --extra sandbox --extra document-readers
uv run python -m benchmarks.public.runner.run_subprocess \
--benchmark browsecomp --pipeline stateful-react-agent --profile default \
...

평가 가이드(evaluation guide)는 자격 증명, 심사위원 사전 점검, 데이터셋, 파일 벤치마크, 실행 및 결과 검사에 대한 표준 운영자 참고 자료입니다. 벤치마크 레지스트리(benchmark registry)에는 데이터셋 키, 기본 파이프라인, 채점 구현 및 확장 지점이 나열되어 있습니다. FrontierSearchBench는 자체 외부 스코어러와 격리 요구 사항을 가지고 있으므로, FrontierSearchBench evaluation에 별도로 문서화되어 있습니다.

BrowseComp, BrowseComp-ZH, xbench-DeepResearch, Humanity's Last Exam (텍스트 전용), SuperChem, FrontierScience-Research, FrontierScience-Olympiad, DeepSearchQA, WideSearch, FrontierSearchBench, OfficeQA, GDPval, APEX, 그리고 OneMillion-Bench.

GDPval은 이 오픈 소스 하네스에서 결정론적 결과물 검증(deterministic deliverable validation)을 사용하며, 에이전트 쌍별 채점기(agentic pairwise grader)는 의도적으로 제외되었습니다. 벤치마크 레지스트리는 각 데이터셋 키, 기본 파이프라인 및 채점 구현에 대한 권위적인 자료입니다.

위 차트는 두 FrontierAgent 워크플로우를 Apodex-1.0 기준선(baseline) 및 선택된 외부 시스템과 비교합니다. Apodex 결과는 여기에 요약되어 있습니다:

| Configuration | APEX-Agents | GDPval | FrontierFinance | FrontierScience-Research | BioMysteryBench | HLE |
|---|---|---|---|---|---|
| Apodex-1.1 Agent Team | 38.5 | 78.8 | 54.3 | 63.3 | 35.3 | 56.1 |
| ... |
이전의 Apodex-1.0 체크포인트는 모델 카드와 서비스 가이드와 함께 Hugging Face 컬렉션에서 여전히 이용 가능합니다.

현재 버전을 인용하려면:

@article{apodex11,
title = {Apodex-1.1: Scaling Agentic Intelligence for Complex Work},
author = {Apodex Team},
...

@misc{frontierchallenge,
title = {FrontierChallenge: Evaluating Scientific Workflow Completion},
author = {Su, Liangcai and Feng, Zhaopeng and Chen, Zhuo and Zhang, Zhen}
...

이전 세대에 대해 구체적으로 언급하는 작업의 경우:

@techreport{apodex10,
title = {Apodex-1.0: A Verification-Centric Agent Team for Discoverative Intelligence},
author = {Apodex Team},
...

Apache 2.0 — LICENSE 참조.