호스티드 에이전트 인프라

호스티드 에이전트 인프라은(는) 무엇을 하나요?

호스티드 에이전트는 로컬 머신이 아닌 원격 샌드박스 환경에서 실행됩니다. 잘 설계되면 무제한 동시성, 일관된 실행 환경 및 멀티플레이어 협업을 제공합니다. 핵심 통찰은 세션 속도가 모델 제공자의 첫 번째 토큰 시간(time-to-first-token)에 의해서만 제한되어야 하며, 사용자가 세션을 시작하기 전에 모든 인프라 설정이 완료되어야 한다는 것입니다.

활성화 시점

다음과 같은 경우에 이 스킬을 활성화하세요:

• 사용자 기기와 독립적으로 실행되는 백그라운드 코딩 에이전트 구축
• 에이전트 워크로드를 위한 샌드박스 실행 환경 설계
• 공유 상태를 가진 멀티플레이어 에이전트 세션 구현
• 다중 클라이언트 에이전트 인터페이스(Slack, 웹, Chrome 확장 프로그램) 생성
• 로컬 머신 제약을 넘어서는 에이전트 인프라 확장
• 에이전트가 병렬 작업을 위해 하위 에이전트를 생성하는 시스템 구축

다른 스킬이 담당하는 인접 작업에 대해서는 이 스킬을 활성화하지 마세요:

• 자율 연구 루프, 참신성 게이트, 롤백 정책 또는 병합 경계 설계: harness-engineering.
• 호스티드 인프라 문제 없이 감독자, 스웜 또는 핸드오프 토폴로지 선택: multi-agent-patterns.
• spawn/status 도구 또는 PR 도구와 같은 호스티드 에이전트가 사용하는 도구 설계: tool-design.
• 호스티드 런타임 자체가 아닌 세션 내 파일 기반 상태 관리: filesystem-context.

핵심 개념

에이전트 실행을 원격 샌드박스 환경으로 이동하여 로컬 실행의 근본적인 한계(리소스 경합, 환경 비일관성, 단일 사용자 제약)를 제거하세요. 원격 샌드박스는 각 세션마다 알려진 양호한 환경 이미지로 격리된 컴퓨팅을 제공하므로 무제한 동시성, 재현 가능한 환경 및 협업 워크플로를 가능하게 합니다.

세 가지 계층으로 아키텍처를 설계하세요. 각 계층은 독립적으로 확장됩니다. 격리된 실행을 위한 샌드박스 인프라, 상태 관리 및 클라이언트 조정을 위한 API 계층, 사용자 상호 작용을 위한 클라이언트 인터페이스를 구축하세요. 이러한 계층을 깔끔하게 분리하여 샌드박스 변경이 클라이언트로 전파되지 않도록 하세요.

세부 주제

샌드박스 인프라

핵심 과제 샌드박스 시작 지연 시간을 제거하세요. 사용자는 몇 초를 넘으면 고장난 것으로 인식합니다. 개발 환경에는 리포지토리 복제, 종속성 설치 및 빌드 단계 실행이 필요합니다. 사용자가 프롬프트를 제출하기 전에 이 모든 작업을 완료하세요.

이미지 레지스트리 패턴 정기적인 주기(30분이 효과적임)로 환경 이미지를 사전 빌드하세요. 이렇게 하면 최신 코드와의 동기화가 전체 복제가 아닌 빠른 델타가 됩니다. 각 이미지에 포함할 내용:

• 알려진 커밋에 복제된 리포지토리
• 설치된 모든 런타임 종속성
• 완료된 초기 설정 및 빌드 명령
• 앱 및 테스트 스위트를 한 번 실행하여 캐시된 파일

세션을 시작할 때 가장 최근 이미지에서 샌드박스를 시작하세요. 리포지토리는 최대 30분까지 오래될 수 있으므로 나머지 git 동기화가 빠릅니다.

스냅샷 및 복원 핵심 지점에서 파일 시스템 스냅샷을 찍어 설정을 다시 실행하지 않고 후속 프롬프트에 대한 즉시 복원을 가능하게 하세요:

• 초기 이미지 빌드 후(기본 스냅샷)
• 에이전트가 변경을 완료했을 때(세션 스냅샷)
• 잠재적 후속 작업을 위한 샌드박스 종료 전

백그라운드 에이전트를 위한 Git 구성 백그라운드 에이전트는 이미지 빌드 중 특정 사용자에 연결되지 않으므로 모든 샌드박스에서 git ID를 명시적으로 구성하세요:

• 복제 중 리포지토리 액세스를 위해 GitHub 앱 설치 토큰 생성
• 커밋 및 푸시 시 git config user.name 및 user.email 설정
• 앱 ID가 아닌 프롬프트 사용자의 ID를 커밋에 사용

웜 풀 전략 볼륨이 큰 리포지토리의 경우 사전 웜업된 샌드박스 풀을 유지하세요. 콜드 스타트가 사용자 불만의 주요 원인이기 때문입니다:

• 사용자가 세션을 시작하기 전에 샌드박스를 준비 상태로 유지
• 새 이미지 빌드가 완료됨에 따라 풀 항목 만료 및 재생성
• 사용자가 입력을 시작하자마자 샌드박스 웜업 시작(예측 웜업)

에이전트 프레임워크 선택

서버 우선 아키텍처 에이전트 프레임워크를 먼저 서버로 구성하고 TUI 및 데스크톱 앱을 얇은 클라이언트로 만드세요. 이렇게 하면 여러 표면에서 에이전트 로직이 중복되는 것을 방지합니다:

• 여러 사용자 정의 클라이언트가 하나의 에이전트 백엔드를 공유
• 모든 상호 작용 표면에서 일관된 동작
• 플러그인 시스템이 클라이언트 변경 없이 기능 확장
• 이벤트 기반 아키텍처가 연결된 모든 클라이언트에 실시간 업데이트 제공

코드를 진실의 원천으로 에이전트가 자체 소스 코드를 읽어 동작을 이해할 수 있는 프레임워크를 선택하세요. 코드를 진실의 원천으로 삼으면 에이전트가 자체 기능에 대해 환각(hallucinate)을 일으키는 것을 방지할 수 있으므로 이를 우선시하세요. 이는 AI 개발에서 과소평가된 실패 모드입니다.

플러그인 시스템 요구 사항 런타임 차단을 지원하는 플러그인 시스템이 필요합니다. 이렇게 하면 핵심 에이전트 로직을 수정하지 않고 안전 제어 및 관찰 가능성을 활성화할 수 있습니다:

• 도구 실행 이벤트 수신(예: tool.execute.before)
• 조건부로 도구 호출 차단 또는 수정
• 런타임에 컨텍스트 또는 상태 주입

속도 최적화

예측 웜업 사용자가 프롬프트를 제출할 때가 아니라 입력을 시작할 때 샌드박스 웜업을 시작하세요. 입력 간격(5-30초)은 대부분의 설정을 완료하기에 충분합니다:

• 사용자 입력과 병렬로 최신 변경 사항 복제
• 사용자가 Enter를 누르기 전에 초기 설정 실행
• 빠른 시작의 경우 사용자가 입력을 마치기 전에 샌드박스 준비 완료

병렬 파일 읽기 최신 기본 브랜치와의 동기화가 완료되지 않았더라도 에이전트가 즉시 파일 읽기를 시작할 수 있도록 허용하세요. 대규모 리포지토리에서 들어오는 프롬프트는 최근에 변경된 파일을 거의 건드리지 않기 때문입니다:

• 에이전트는 git 동기화를 기다리지 않고 즉시 조사 가능
• 동기화가 완료될 때까지 파일 편집(읽기 아님) 차단
• 이 분리는 안전합니다. 30분의 읽기 시간 데이터 부실은 조사에 거의 중요하지 않기 때문입니다.

빌드 시간 작업 최대화 가능한 모든 것을 이미지 빌드 단계로 이동하세요. 빌드 시간은 사용자에게 보이지 않기 때문입니다:

• 전체 종속성 설치
• 데이터베이스 스키마 설정
• 초기 앱 및 테스트 스위트 실행(캐시 채우기)

자기 복제 에이전트

에이전트가 생성한 세션 에이전트가 새 세션을 생성할 수 있는 도구를 구축하세요. 프론티어 모델은 작업을 분해하고 하위 작업을 조정할 수 있기 때문입니다:

• 다른 리포지토리 간 연구 작업
• 대규모 변경을 위한 병렬 하위 작업 실행
• 하나의 주요 작업에서 여러 개의 작은 PR

세 가지 기본 요소를 노출하세요: 지정된 매개변수로 새 세션 시작, 모든 세션의 상태 읽기(체크인 기능), 하위 세션이 병렬로 실행되는 동안 주요 작업 계속.

자기 복제를 위한 프롬프트 엔지니어링 에이전트가 인라인 작업 대신 하위 세션을 생성해야 하는 시점을 안내하는 프롬프트를 엔지니어링하세요:

• 교차 리포지토리 탐색이 필요한 연구 작업
• 모놀리식 변경을 더 작은 PR로 분할
• 다양한 접근 방식의 병렬 탐색

API 계층

세션별 상태 격리 세션별로 상태를 격리하세요(세션당 SQLite가 효과적임). 교차 세션 간섭은 미묘하고 디버깅하기 어려운 실패 모드이기 때문입니다:

• 세션당 전용 데이터베이스
• 어떤 세션도 다른 세션의 성능에 영향을 미칠 수 없음
• 수백 개의 동시 세션을 처리하는 아키텍처

실시간 스트리밍 모든 에이전트 작업을 실시간으로 스트리밍하세요. 고주파 피드백은 사용자 신뢰에 중요하기 때문입니다:

• 모델 제공자의 토큰 스트리밍
• 도구 실행 상태 업데이트
• 파일 변경 알림

휴면 기간 동안 컴퓨팅 비용을 줄이면서 열린 연결을 유지하기 위해 하이버네이션 API와 함께 WebSocket 연결을 사용하세요.

클라이언트 간 동기화 모든 클라이언트(채팅 인터페이스, Slack 봇, Chrome 확장 프로그램, 웹 인터페이스, VS Code 인스턴스)에서 동기화되는 단일 상태 시스템을 구축하세요. 사용자는 표면을 자주 전환하고 연속성을 기대하기 때문입니다. 모든 변경 사항이 세션 상태에 동기화되어 원활한 클라이언트 전환이 가능합니다.

멀티플레이어 지원

멀티플레이어가 중요한 이유 처음부터 멀티플레이어를 위해 설계하세요. 적절한 동기화 아키텍처를 사용하면 추가하는 데 거의 비용이 들지 않으며 고가치 워크플로를 잠금 해제하기 때문입니다:

• 비엔지니어에게 AI를 효과적으로 사용하는 방법 가르치기
• 여러 팀원과의 라이브 QA 세션
• 즉각적인 변경이 포함된 실시간 PR 검토
• 협업 디버깅 세션

구현 요구 사항 세션이 단일 작성자에 연결되지 않도록 데이터 모델을 구축하세요. 작성자가 하드코딩되면 멀티플레이어가 조용히 실패하기 때문입니다:

• 각 프롬프트에 작성자 정보 전달
• 코드 변경을 프롬프트한 사용자에게 귀속
• 즉시 협업을 위한 세션 링크 공유

인증 및 권한 부여

사용자 기반 커밋 앱이 아닌 사용자를 대신하여 PR을 열기 위해 GitHub 인증을 사용하세요. 이렇게 하면 감사 추적이 보존되고 사용자가 자신의 AI 생성 변경 사항을 승인하는 것을 방지할 수 있습니다:

• PR 생성을 위한 사용자 토큰 획득
• PR이 봇이 아닌 사람이 작성한 것으로 표시됨

샌드박스-API 흐름 샌드박스 권한을 최소화하면서 API가 민감한 작업을 처리할 수 있도록 다음 순서를 따르세요:

1. 샌드박스가 변경 사항을 푸시합니다(git 사용자 구성 업데이트).
2. 샌드박스가 브랜치 이름과 세션 ID와 함께 이벤트를 API에 보냅니다.
3. API가 사용자의 GitHub 토큰을 사용하여 PR을 생성합니다.
4. GitHub 웹훅이 PR 이벤트를 API에 알립니다.

클라이언트 구현

Slack 통합 내부 채택을 위해 Slack을 첫 번째 배포 채널로 우선시하세요. 팀원들이 다른 사람들이 사용하는 것을 보면서 입소문 루프를 만들기 때문입니다:

• 문법 불필요, 자연어 채팅 인터페이스
• 작업할 리포지토리를 결정하는 분류기(리포지토리 설명이 있는 빠른 모델) 구축
• 일반적인 리포지토리에 대한 힌트 포함; 모호한 경우 "알 수 없음" 허용

웹 인터페이스 다음 기능을 갖춘 웹 인터페이스를 구축하세요. 주요 파워 유저 표면 역할을 하기 때문입니다:

• 데스크톱 및 모바일에서 에이전트 작업의 실시간 스트리밍
• 샌드박스 내에서 실행되는 호스티드 VS Code 인스턴스
• 시각적 검증을 위한 스트리밍 데스크톱 보기
• PR의 전후 스크린샷
• 통계 페이지: 병합된 PR로 이어진 세션(주요 지표), 시간 경과에 따른 사용량, 실시간 "인간 프롬프트" 수

Chrome 확장 프로그램 비엔지니어링 사용자를 위해 Chrome 확장 프로그램을 구축하세요. DOM 및 React 내부 추출은 원시 스크린샷보다 더 높은 정밀도를 더 낮은 토큰 비용으로 제공하기 때문입니다:

• 스크린샷 도구가 있는 사이드바 채팅 인터페이스
• 원시 이미지 대신 DOM/React 내부 추출
• 관리 기기 정책을 통해 배포(Chrome 웹 스토어 우회)

실용적인 지침

호스티드 에이전트 설계 체크리스트

시스템을 구축하기 전에 이러한 인프라 속성을 명시적으로 결정하세요:

1. 샌드박스 수명 주기: 세션 시작, 스냅샷, 복원, 시간 초과 및 종료 방법.
2. 이미지 및 웜 풀 정책: 이미지 재구축 빈도, 사전 계산된 캐시, 웜 샌드박스 만료 시점.
3. 읽기/쓰기 동기화: 에이전트가 리포지토리 동기화 완료 전에 읽을 수 있는지 여부와 쓰기를 차단 해제하는 이벤트.
4. 세션별 상태 격리: 어떤 스토리지가 하나의 세션에 속하고, 무엇이 공유되며, 교차 세션 간섭이 방지되는 방법.
5. 인증 및 커밋 ID: 어떤 작업이 앱 토큰을 사용하고, 어떤 작업이 사용자 토큰을 사용하며, 커밋이 귀속되는 방법.
6. 출력 추출: 브랜치, PR, 파일, 로그, 스크린샷 및 세션 요약이 샌드박스를 떠나는 방법.
7. 예산 및 해체: 최대 런타임, 비용 상한, 유휴 정책 및 강제 정리 동작.

후속 메시지 처리

실행 중 전송된 후속 메시지를 큐에 넣을지 삽입할지 선택하세요. 큐를 선호하세요. 관리하기가 더 간단하고 사용자가 에이전트가 작업하는 동안 다음 단계에 대한 생각을 보낼 수 있기 때문입니다. 필요할 때 에이전트를 실행 중간에 중지하는 메커니즘을 구축하세요. 없으면 사용자가 갇힌 느낌을 받을 수 있기 때문입니다.

중요한 지표

이러한 지표를 추적하세요. 허영 사용량이 아닌 실제 가치를 나타내기 때문입니다:

• 병합된 PR로 이어진 세션(주요 성공 지표)
• 세션 시작부터 첫 번째 모델 응답까지의 시간
• PR 승인율 및 수정 횟수
• 리포지토리 전체에서 에이전트가 작성한 코드 비율

채택 전략

의무가 아닌 가시성을 통해 내부 채택을 유도하세요. 강제된 사용은 반감을 불러일으키기 때문입니다:

• 가시성을 위해 공개 공간(Slack 채널)에서 작업
• 제품이 입소문 루프를 만들도록 함
• 기존 도구보다 강제로 사용하지 않음
• 가상의 요구 사항이 아닌 사람들의 필요에 맞춰 구축

예시

예시 1: 백그라운드 코딩 세션 수명 주기

사용자 프롬프트
-> API가 현재 이미지에서 웜 샌드박스 할당
-> 샌드박스가 최신 브랜치 델타 동기화
-> 읽기는 즉시 허용, 쓰기는 동기화 완료까지 차단
-> 에이전트가 격리된 작업 공간 내에서 편집 및 테스트
-> 샌드박스가 최종 파일 시스템 스냅샷
-> 브랜치 푸시
-> API가 사용자 토큰을 사용하여 PR 생성
-> 세션 요약, 로그 및 PR URL이 클라이언트에 반환됨

이 시퀀스는 설정 작업을 사용자에게 보이지 않는 경로 밖에 유지하면서 코드 변경에 대한 감사 가능성과 사용자 소유권을 유지합니다.

예시 2: 경계 결정

작업이 "잠긴 루브릭과 PR 승인으로 에이전트 루프를 며칠 동안 실행"하는 것이라면 harness-engineering을 사용하세요. 작업이 "웜 풀, 세션 스냅샷, 스트리밍 클라이언트 및 사용자 작성 PR과 함께 원격 샌드박스에서 해당 루프를 실행"하는 것이라면 이 스킬을 사용하세요.

지침

1. 정기적인 주기(30분이 좋은 기본값)로 환경 이미지 사전 빌드
2. 사용자가 제출할 때가 아니라 입력을 시작할 때 샌드박스 웜업 시작
3. git 동기화 완료 전 파일 읽기 허용; 쓰기만 차단
4. 에이전트 프레임워크를 서버 우선으로 구성하고 클라이언트는 얇은 래퍼로 구성
5. 세션별 상태 격리로 교차 세션 간섭 방지
6. 앱이 아닌 프롬프트한 사용자에게 커밋 귀속
7. 병합된 PR을 주요 성공 지표로 추적
8. 처음부터 멀티플레이어 구축; 적절한 동기화 아키텍처로 거의 비용이 들지 않음

주의 사항

1. 콜드 스타트 지연 시간: 첫 번째 샌드박스 시작에는 30-60초가 소요되며 사용자는 이를 고장난 것으로 인식합니다. 웜 풀을 사용하여 이 문제를 완화하세요.
2. 상태 복원 실패: 스냅샷에서 복원이 실패할 수 있습니다. 세션을 다시 시작하고 이전 작업을 재현하는 폴백을 계획하세요.
3. Git 권한 누락: 샌드박스에서 git 푸시가 실패하면 전체 워크플로가 중단됩니다. 설정에서 git 자격 증명을 테스트하세요.
4. 보안 경계: 샌드박스 경계가 약하면 데이터 유출이 발생할 수 있습니다. 네트워크 액세스를 제한하고 샌드박스 구성을 정기적으로 감사하세요.