OpenProject Agent Engine은 OpenProject 작업 패키지를 확인해 pi 코딩 에이전트에 배정하는 오픈소스 도구다. OpenProject를 기록의 기준으로 삼으며, 엔진이 작업을 선점하고 에이전트별 복제본을 준비한 뒤 프롬프트를 만들고 에이전트를 실행한다. 이후 GitHub와 OpenProject를 대조해 결과를 확인하고 상태 변경까지 처리한다. 에이전트는 상태를 직접 바꾸지 않는다.
Docker 이미지와 이미지 태그를 제공한다. 데모 애니메이션도 확인할 수 있다.
설치와 시작
필요한 환경은 Docker, 프로젝트가 설정된 OpenProject 17(API v3)과 최초 1회 관리자 접근 권한, 각 프로젝트의 GitHub 저장소 및 저장소에 푸시하고 풀 리퀘스트를 병합할 수 있는 토큰이다.
빠른 시작 절차는 다음과 같다.
- docs/OPENPROJECT_SETUP.md를 참고해 인스턴스에서 상태, 프로젝트 사용자 지정 필드
GIT_REPO, 작업 패키지 사용자 지정 필드AGENT, Agent Worker 역할을 한 번 설정한다. docker/에서 대화형 설정을 실행한다.git clone https://github.com/310networks/openproject-agent-engine op-agent-engine cd op-agent-engine/docker && ./agent-init.sh를 실행하면 된다. 설정을 다시 실행해도 안전하다. OpenProject 토큰을 다시 입력하려면--reprompt-tokens를 사용한다.- 스택을 시작하기 전에
docker/.env를 완성한다.GH_TOKEN을 추가해야 한다. 전용 검토자 계정을 사용하는 경우(예: 브랜치 보호 규칙 적용) 선택적으로GH_TOKEN_REVIEWER,GIT_REVIEWER_NAME,GIT_REVIEWER_EMAIL도 추가한다. docker compose up -d로 스택을 시작하고docker compose logs -f engine으로 엔진 로그를 확인한다.- OpenProject에 프로젝트를 추가하거나 프로젝트의
GIT_REPO또는AGENT설정을 바꾼 뒤에는docker compose restart engine을 실행한다.docker/.env를 바꾼 뒤에는 환경 변수를 적용하도록 컨테이너를 다시 만들기 위해docker compose up -d engine을 실행한다.
대시보드는 http://127.0.0.1:8765에서 제공한다. 자세한 내용은 docs/DASHBOARD.md를 참고한다.
환경 변수와 프로젝트 설정
agent-init.sh는 OpenProject 설정, 에이전트 토큰, 제공자 키를 기록한다. GitHub 토큰은 스크립트가 설정하지 않으므로 스택을 시작하기 전에 직접 docker/.env에 추가해야 한다.
| 변수 | 의미 |
|---|---|
OP_BASE_URL | OpenProject URL |
OP_PROJECT | 프로젝트 식별자. 하나, 쉼표로 구분한 목록 또는 GIT_REPO가 설정된 모든 프로젝트를 뜻하는 *를 지정한다. |
OP_ENGINE_TOKEN | 런타임 사용자(관리자)의 API 토큰 |
AGENT_MODEL | 모든 에이전트에 적용할 <provider>/<model> 형식의 모델. 제공자는 인증 정보 또는 엔드포인트 변수도 선택한다. |
AGENT_MODEL_<AGENT> | 에이전트별 선택 모델. AGENT_MODEL_FRONTEND, ..._BACKEND, ..._DESIGNER, ..._REVIEWER를 지정할 수 있으며, 같은 제공자를 사용한다. |
OP_TOKEN_FRONTEND | frontendEngineer의 토큰 |
OP_TOKEN_BACKEND | backendEngineer의 토큰 |
OP_TOKEN_DESIGNER | leadDesigner의 토큰 |
OP_TOKEN_REVIEWER | codeReviewer의 토큰 |
OPENROUTER_API_KEY 또는 다른 제공자 키 | pi에 사용할 모델 제공자 키 하나 |
LLAMA_BASE_URL | 로컬 llama.cpp 제공자를 사용할 때의 llama.cpp 라우터 URL |
GH_TOKEN | 복제, 푸시, 풀 리퀘스트 조회에 사용하는 GitHub 토큰 |
브랜치 보호 규칙에서 승인자나 병합 계정이 풀 리퀘스트 작성자와 달라야 한다면 codeReviewer에 별도의 GitHub 계정을 제공한다. 이때 GH_TOKEN_REVIEWER를 설정하고, 선택적으로 GIT_REVIEWER_NAME과 GIT_REVIEWER_EMAIL도 지정한다. 검토자는 gh와 git의 계정을 해당 계정으로 전환해 병합 전에 승인 검토를 제출할 수 있다. 별도 토큰이 없으면 모든 에이전트가 GH_TOKEN을 계속 사용한다. 두 토큰이 같은 계정에 속하면 승인자가 달라야 하는 브랜치 보호 규칙이 여전히 병합을 막는다. 이 값들은 직접 docker/.env에 추가해야 하며 설정 스크립트는 더 이상 GitHub 토큰을 묻지 않는다.
모니터링할 각 프로젝트에는 GitHub 저장소를 담은 프로젝트 속성 GIT_REPO가 있어야 한다. 값은 owner/name 또는 github.com URL로 지정한다. 이 속성은 Administration → Projects → Project attributes에서 한 번 만들고 For all projects를 선택한다. 속성 하나가 모든 프로젝트에 할당되므로 프로젝트별 활성화 설정은 없다. AGENT 필드 설정과 마찬가지로 한 번만 설정하면 된다. docker/agent-init.sh가 설정 과정에서 이를 안내한다.
이미지에 포함된 에이전트 팀은 고정되어 있으며, 각 에이전트마다 OpenProject 계정 하나와 토큰 하나를 사용한다.
AGENT 필드 값 | 로그인 | 종류 |
|---|---|---|
FRONTEND | frontendEngineer | 구현자 |
BACKEND | backendEngineer | 구현자 |
LEAD_DESIGNER | leadDesigner | 구현자 |
REVIEWER | codeReviewer | 검토자 |
스크립트가 기록하는 모델 설정의 예는 AGENT_MODEL=openrouter/deepseek/deepseek-v4.1-flash-1017이다.
로컬 llama.cpp 라우터는 호스팅 제공자 키 대신 기본 제공자로 사용할 수 있다. AGENT_MODEL=llama.cpp/<model>과 라우터 URL을 가리키는 LLAMA_BASE_URL을 설정한다. 서버를 --api-key로 시작했다면 LLAMA_API_KEY도 설정해야 한다. 엔진 컨테이너 내부에서 해당 URL에 접속할 수 있어야 한다. 자세한 내용은 docs/CONFIG.md의 llama.cpp 안내를 참고한다.
동시 실행 수, 실행 간격, 상태 이름, 경로, 공유 git 사용자 정보에는 기본값이 설정되어 있다. 전체 설정은 docs/CONFIG.md와 주석이 포함된 docker/.env.example에서 확인할 수 있다.
티켓 처리와 상태 전환
| 관찰된 상태 | 엔진 동작 | 실행 작업 | 확인된 결과 | 전환 상태 |
|---|---|---|---|---|
New, 처리 가능, AGENT 설정됨 | 선점 후 In Progress로 변경 | 구현 | 풀 리퀘스트 생성 또는 BLOCKED | Ready for Review 또는 On Hold |
Ready for Review, 풀 리퀘스트 있음 | 선점 후 In Testing으로 변경 | 검토 | 풀 리퀘스트 병합 또는 REJECTED | Closed 또는 Rejected |
Ready for Review, 풀 리퀘스트 없음 | — | — | — | On Hold로 바꾸고 댓글 추가 |
Rejected, 처리 가능 | 선점 후 In Progress로 변경 | 수정 | 구현 작업과 동일 | 구현 작업과 동일 |
On Hold는 종료 상태다. 사람이 티켓 상태를 바꾸기 전까지 엔진은 해당 티켓을 무시한다. 브랜치 이름은 티켓마다 하나씩 만드는 op-<project>-<wp> 형식이다. 에이전트별 실행 횟수는 MAX_RUNS_PER_AGENT로 제한하며 기본값은 1이다. 엔진이 작성하는 댓글은 모두 ENGINE:으로 시작한다.
문서와 기여
저장소 문서에는 다음 내용이 담겨 있다.
- docs/DOCKER.md: 이미지 내부 구조, 볼륨, 릴리스, 문제 해결
- docs/OPENPROJECT_SETUP.md: 상태,
GIT_REPO프로젝트 속성,AGENT작업 패키지 사용자 지정 필드, Agent Worker 역할, 관리자 엔진 사용자 - docs/CONFIG.md: 전체 환경 변수, 제공자 키, 에이전트 팀, CLI 참고 자료
- docs/DASHBOARD.md: 읽기 전용 웹 UI
- docs/RUNBOOK.md: 상태, 일시 중지, 실행 검사,
On Hold처리, 복구 - docs/ACCEPTANCE.md: 가짜 에이전트 테스트와 수동 승인 체크리스트
- docs/CURRENT_STATE.md: 구현된 아키텍처, 제어 흐름, 상태, 한계
이슈와 풀 리퀘스트를 받는다. 풀 리퀘스트에서는 테스트 모음(ruff, mypy, pytest)을 실행한다. .github/, docker/, pyproject.toml 변경에는 코드 소유자의 검토가 필요하며, 자세한 내용은 .github/CODEOWNERS에 있다.
취약점을 공개 이슈로 올리지 말고 비공개 제보 절차를 이용한다. OpenProject Agent Engine은 MIT License로 배포되는 오픈소스 소프트웨어다.
댓글 (0)
로그인하면 이 기사에 내 생각을 남길 수 있어요