실행 태스크
에이전트의 한 번의 실행이 큐에 들어가고, 실행되고, 중지되고, 재시도되는 방식을 알아봅니다.
에이전트가 작업을 시작할 때마다 Melso가 실행 태스크(task)를 만듭니다. 이 기록에는 무엇이 실행을 트리거했는지, 어느 에이전트에게 전달되었는지, 현재 어디까지 진행되었는지, 최종적으로 성공했는지가 담깁니다.
이슈와 실행 태스크
이슈에는 한 작업의 목표, 논의, 담당자, 최종 상태가 저장되고, 실행 태스크에는 에이전트가 이 작업을 한 번 실행한 기록이 저장됩니다.
| 이슈 | 실행 태스크 | |
|---|---|---|
| 기록하는 내용 | 계속 진행되는 작업 하나 | 에이전트의 실행 한 번 |
| 유지 기간 | 반복해서 논의하고 보충하고 다시 할당할 수 있음 | 트리거된 시점부터 완료, 실패, 취소될 때까지 |
| 수량 관계 | 이슈 하나에 여러 실행이 포함될 수 있음 | 실행마다 독립된 기록이 있음 |
따라서 같은 이슈를 여러 에이전트에게 차례로 맡기거나 실패 후 다시 실행할 수 있습니다. 매번 새 태스크가 생성되며 이전 기록은 덮어쓰지 않습니다.
트리거 출처
다음 작업은 모두 실행을 트리거할 수 있습니다.
- 이슈를 에이전트 또는 스쿼드에 할당
- 댓글에서 에이전트 멘션
- 대화에서 에이전트에게 메시지 전송
- 일정 또는 외부 이벤트로 자동화 트리거
각 진입점이 제공하는 컨텍스트는 다르지만 실행 방식은 같습니다. Melso가 태스크를 만들고 런타임이 가져간 뒤 에이전트에 설정된 AI 코딩 도구를 호출합니다.
실행 과정
태스크는 일반적으로 다음 상태를 거칩니다.
| 상태 | 의미 |
|---|---|
deferred | 나중에 트리거되도록 예약되었으며 지정 시간이 되면 큐에 들어갑니다. |
queued | 런타임이 가져가기를 기다립니다. |
dispatched | 런타임이 가져갔고 AI 코딩 도구를 시작하고 있습니다. |
waiting_local_directory | 대상 로컬 디렉터리를 다른 실행이 사용 중이어서 디렉터리 잠금 해제를 기다립니다. |
running | AI 코딩 도구가 실행 중입니다. |
completed | 이번 실행이 정상적으로 끝났습니다. |
failed | 실행 중 오류가 발생했거나 중단되었습니다. |
cancelled | 실행을 수동으로 중지했습니다. |
런타임이 온라인이면 새 태스크가 보통 빠르게 시작됩니다. 태스크가 큐에 들어간 뒤 런타임이 오프라인이 되면 복구될 때까지 큐에서 기다립니다. 2시간 넘게 수령되지 않으면 태스크가 실패로 끝납니다.
트리거하기 전에 대상 런타임이 오프라인임을 시스템이 이미 아는 경우 일부 즉시 실행 작업은 수령할 수 없는 태스크를 만들지 않고 현재 실행할 수 없다고 바로 알립니다.
heartbeat가 정상인 런타임은 장시간 태스크도 실행할 수 있으며 서버는 실행 시간이 길다는 이유만으로 강제 종료하지 않습니다. 런타임은 실제 활동을 기준으로 프로세스가 멈췄는지 판단합니다. 관련 설정은 환경 변수를 참고하세요.
실행 기록 확인
이슈를 열면 실행 로그에서 해당 이슈가 만든 모든 태스크를 볼 수 있습니다. 각 줄에는 트리거 출처, 실행 에이전트, 상태, 시간이 표시됩니다.
여기에서 다음 작업을 할 수 있습니다.
- 실행 기록을 열어 에이전트 메시지, 도구 호출, 오류 정보 확인
- 나중에 실행하도록 예약된 태스크, 큐 대기 중인 태스크, 시작 중인 태스크, 로컬 디렉터리를 기다리는 태스크, 실행 중인 태스크 중지
- 실패하거나 취소된 태스크 재시도
이슈의 담당자나 상태를 바꿔도 이미 시작된 실행은 중지되지 않습니다. 중단하려면 실행 로그에서 해당 실행 태스크를 중지하세요. 이슈를 삭제할 때만 연결된 활성 태스크가 함께 취소됩니다.
실패와 자동 재시도
런타임의 일시적인 오프라인, 데몬 재시작, 실행 timeout, AI 코딩 도구의 네트워크 중단 같은 일시적 장애는 자동 재시도를 트리거할 수 있습니다. 일반 태스크는 기본적으로 최대 두 번 실행되고 도구 네트워크 중단은 최대 세 번 실행됩니다.
에이전트 자체가 반환한 오류는 보통 자동으로 재시도되지 않습니다. 인증 만료, 사용량 부족, 설정 오류, 모델이 요청을 완료하지 못한 경우에는 먼저 원인을 해결한 뒤 수동으로 재시도해야 합니다.
자동화의 실행만 모드는 다음 예약 실행과 겹치지 않도록 자동 재시도하지 않습니다. 이슈 만들기 모드는 일반 이슈 태스크를 생성하므로 인프라 장애에 위 규칙을 적용해 재시도합니다. 두 모드 모두 자동화 실행 기록에서 최종 결과를 확인할 수 있습니다.
이슈에 다른 활성 태스크가 없고 실행을 기다리는 새 재시도도 없다면 실패 시 in_progress 상태의 이슈가 todo로 돌아갑니다.
실패 원인 참조
실행 로그와 사용량 통계의 일반적인 실패 원인은 두 종류입니다. 접두사가 없는 이유 코드는 플랫폼이 기록하고, agent_error.*는 AI 코딩 도구의 오류를 분류한 값입니다.
플랫폼 측
| 원인 | 의미 | 처리 방법 |
|---|---|---|
runtime_offline | 실행 중 런타임이 오프라인이 됨 | 런타임을 복구한 뒤 재시도합니다. 데몬과 런타임 참고 |
queued_expired | 2시간 넘게 큐에서 기다렸지만 런타임이 가져가지 않음 | 런타임이 온라인인지 확인한 뒤 재시도 |
runtime_recovery | 데몬 재시작 후 중단된 실행을 회수함 | 바로 재시도 |
cancelled | 수동으로 중지되었거나 보관 또는 삭제와 함께 취소됨 | 별도 처리 불필요 |
timeout | 데몬에 설정된 실행 시간 상한을 초과함 | 이슈 범위를 줄이거나 데몬의 agent_timeout 조정 |
iteration_limit | 실행 반복 횟수 상한에 도달함 | 이슈 범위 축소 |
agent_blocked | 에이전트가 계속 진행할 수 없다고 직접 보고함 | 댓글의 설명에 따라 정보 보충 |
api_invalid_request | 플랫폼 API가 잘못된 요청을 거부함 | 재시도하고 반복되면 문제 신고 |
codex_semantic_inactivity | Codex가 오랫동안 유효한 출력을 내지 않아 멈춘 것으로 판단됨 | 재시도하거나 Codex 정체 timeout 조정 |
도구 측(agent_error.*, 접두사 생략)
| 원인 | 의미 | 처리 방법 |
|---|---|---|
provider_auth_or_access | 모델 서비스 인증 실패 또는 접근 권한 없음(401/403) | 해당 AI 코딩 도구에 다시 로그인하거나 API key 확인 |
provider_quota_limit | 사용량 또는 잔액 소진(402) | 충전하거나 계정 변경 |
provider_capacity_or_rate_limit | rate limit 또는 용량 부족(429/529) | 나중에 재시도 |
provider_server_error | 모델 서비스 오류(5xx) | 나중에 재시도 |
provider_network | 모델 서비스와의 네트워크 오류 | 자동 재시도됩니다. 계속 발생하면 실행 컴퓨터의 네트워크 확인 |
model_not_found_or_unavailable | 모델이 없거나 현재 사용할 수 없음 | 에이전트 설정에서 사용 가능한 모델 선택 |
context_overflow | 컨텍스트가 모델 window를 초과함 | 이슈 범위를 줄이거나 입력 내용 축소 |
missing_config | API key 등 필수 설정이 없음 | 에이전트 환경 변수 또는 도구 설정 보완 |
runtime_missing_executable | AI 코딩 도구 실행 파일을 찾을 수 없음 | 도구를 다시 설치합니다. AI 코딩 도구 설치 참고 |
runtime_version_unsupported | AI 코딩 도구 버전이 너무 오래됨 | 도구 업그레이드 |
process_failure | 도구 프로세스가 비정상 종료됨 | 실행 로그에서 원인을 확인한 뒤 재시도 |
empty_or_unparseable_output | 도구 출력이 없거나 해석할 수 없음 | 재시도하고 반복되면 도구 설치 확인 |
agent_timeout | 도구가 오랫동안 응답하지 않아 종료됨 | 재시도하거나 이슈 범위 축소 |
unknown | 분류하지 못한 실패 | 실행 로그의 원본 오류 확인 |
수동 재시도
실행 로그에서 특정 줄의 재시도 버튼을 클릭하면 당시 이 태스크를 실행한 에이전트가 다시 호출됩니다. 이후 이슈 담당자가 바뀌었더라도 새 담당자를 사용하지 않습니다.
재시도할 때 이전 실행이 로컬 디렉터리에 이미 기록한 파일을 가능한 한 유지합니다. 원래 세션이 계속 안전하고 같은 런타임이 태스크를 가져가면 이전 세션도 이어갑니다. 컨텍스트 overflow나 유효하지 않은 요청처럼 세션을 오염시키는 오류가 있었다면 원래 작업 디렉터리에서 새 세션을 시작합니다. 원래 디렉터리가 없으면 새 작업 디렉터리를 사용합니다.
CLI로 현재 이슈를 다시 실행할 수도 있습니다.
melso issue rerun <issue-id>이 방법은 특정 과거 태스크를 지정하지 않으므로 이슈의 현재 에이전트 담당자를 사용하고 새 세션과 작업 디렉터리에서 시작합니다.
실행 완료와 이슈 완료
completed는 이번 실행이 정상적으로 끝났다는 뜻일 뿐 이슈 목표가 확인되었다는 뜻은 아닙니다. 결과를 확인하고, 논의를 이어가고, 요구 사항을 보충하거나 에이전트를 다시 트리거할 수 있습니다.
이슈의 완료 여부는 실제 작업 진행 상황과 이슈 상태를 기준으로 판단합니다.
상태와 timeout 빠른 참조
다음 수치는 서버 기본 설정이며 문제를 확인할 때 빠르게 비교할 수 있습니다.
| 상태 | 의미 | timeout과 결과 |
|---|---|---|
deferred | 나중에 트리거되도록 예약됨 | 예정 시간이 되면 queued로 들어가고 이후 아래 규칙에 따라 시간을 계산합니다. |
queued | 런타임이 가져가기를 기다림 | 2시간 넘게 수령되지 않으면 실패로 끝나며 자동 재시도하지 않습니다. |
dispatched | 런타임이 가져갔고 도구를 시작 중 | 5분 넘게 머물면 실패로 처리합니다. |
waiting_local_directory | 로컬 디렉터리 잠금 해제를 기다림 | 별도 timeout이 없으며 디렉터리가 해제되면 시작 과정으로 돌아갑니다. |
running | AI 코딩 도구 실행 중 | 고정 시간 상한이 없습니다. 런타임 heartbeat로 생존을 판단하며 15초마다 heartbeat를 보냅니다. heartbeat를 잃은 런타임은 늦어도 약 3분 뒤 오프라인으로 판단되고 그 위의 태스크도 실패합니다. |
자동 재시도는 아래의 일시적 장애만 포함하며 이슈 또는 대화에 연결된 태스크에만 적용됩니다. 자동화의 실행만 모드는 제외됩니다.
| 자동 재시도 가능한 실패 원인 | 실행 횟수 상한 |
|---|---|
| 런타임 오프라인 | 기본 2회(첫 실행 + 재시도 1회) |
| 데몬 재시작 후 회수 | 기본 2회 |
| 플랫폼의 실행 timeout 판단 | 기본 2회 |
| Codex가 오랫동안 유효한 출력을 내지 않음 | 기본 2회 |
| 스킬 패키지 다운로드 실패 | 기본 2회(이때 에이전트 프로세스는 아직 시작하지 않았으며 내려받은 패키지는 로컬 캐시 사용) |
| 도구 네트워크 중단 | 최대 3회, 마지막 실행은 약 5초 뒤 시작 |
그 밖의 실패 원인(인증, 사용량, 설정, 모델 등)은 자동 재시도하지 않습니다. 원인을 해결한 뒤 수동으로 재시도해야 합니다.
다음 단계
- 데몬과 런타임 — 태스크가 어느 컴퓨터에서 실행되는지 알아봅니다.
- 이슈를 에이전트에게 할당하기 — 이슈에서 실행을 시작합니다.
- 에이전트 멘션하기 — 댓글에서 요구 사항을 보충하거나 다른 에이전트를 참여시킵니다.