알파 경고: useAgent는 현재 활발히 개발 중입니다. 릴리스 간에 API와 스키마가 변경될 수 있으므로 안정성이 중요하다면 릴리스 태그를 고정하세요.
useAgent란 무엇인가요?
useAgent는 Claude Code, Codex, OpenCode와 같은 에이전트를 실행하기 위한 오픈 소스 AI 동료 플랫폼입니다. 에이전트는 대화형 답변만 반환하는 대신 격리된 Linux 환경에서 작업하며, 완성된 웹사이트, 프레젠테이션, 스프레드시트, 조사 보고서와 테스트가 완료된 풀 리퀘스트를 제공할 수 있습니다.
각 스레드에는 터미널, 저장소, 브라우저, noVNC를 통한 가상 데스크톱이 포함된 워크스테이션이 할당됩니다. 실행은 Postgres의 이벤트 소싱 타임라인으로 표현되므로 완료 후에도 내구성이 유지되고, 재생 및 검사가 가능합니다.
주요 기능
- 여러 에이전트를 위한 하나의 인터페이스: 공급자별 엔진이 표준 이벤트 계약을 통해 통신합니다.
- 내구성 있는 실행: 백엔드가 재시작되어도 실행이 유지되며, 복구 과정에서 활성 세션을 다시 확인하고 완료된 작업을 인수할 수 있습니다.
- 격리된 Linux 샌드박스: 모든 스레드에 별도의 워크스테이션이 할당됩니다. Daytona와 CubeSandbox가 공유 샌드박스 계약을 구현합니다.
- 신뢰할 수 있는 도구 게이트웨이: 자격 증명은 에이전트 샌드박스에 들어가지 않고 제어 플레인에 남습니다.
- 사람의 승인: 파괴적인 도구 호출은 웹 인터페이스나 Slack에서 승인을 받을 때까지 일시 중지되며, 승인 후 인자에绑定되고 한 번만 사용할 수 있는 권한으로 재개됩니다.
- GitHub 기반 스킬: 팀은 버전이 지정된
SKILL.md파일을 가져오고 변경 사항을 동기화하며, 관련 스킬을 에이전트 작업에 우선순위로 반영할 수 있습니다. - 조직 컨텍스트: 지식 검색에는 인용이 포함되며, 팀 메모리는 사람이 검토하는 학습 흐름을 사용합니다.
- 네이티브 아티팩트: 플랫폼은 네이티브 렌더러를 사용해 버전 관리되는 DOCX, XLSX, PPTX, PDF 파일을 지원합니다.
- 여러 진입 채널: 웹 애플리케이션, Slack, REST API 또는 일정에서 작업을 전달할 수 있습니다.
아키텍처 작동 방식
useAgent는 자체 호스팅 제어 플레인과 에이전트가 작업하는 환경을 분리합니다. 모든 진입 채널은 동일한 실행 경로를 통해 실행을 생성합니다. 엔진 어댑터는 공급자별 활동을 표준 이벤트로 변환하며, 각 스레드에는 격리된 샌드박스가 할당됩니다.
특히 중요한 아키텍처 속성은 다음 세 가지입니다.
- 엔진을 교체할 수 있습니다: 엔진을 변경해도 스레드, 아티팩트 또는 메모리의 공통 표현을 교체할 필요가 없습니다.
- Postgres가 단일 진실 공급원입니다: 모든 실행이 이벤트 로그로 저장되므로 재시작 후에도 정확한 재생과 검사가 가능합니다.
- 시크릿은 샌드박스 외부에 보관됩니다: 통합 기능은 신뢰할 수 있는 게이트웨이를 통해 형식이 지정된 도구로 노출되며, 자격 증명은 제어 플레인에만 저장됩니다.
저장소 구조
frontend/에는 세션, 스킬, 플레이북, 위키, 아티팩트, 자동화 및 설정을 위한 제품 인터페이스가 포함됩니다.backend/에는 인증, 실행 오케스트레이션, 엔진 어댑터, 샌드박스, 지식, 메모리, 아티팩트 및 커넥터가 포함됩니다.packages/에는 공유 이벤트 계약, 작업 단위, 아티팩트 형식, 렌더러 및 관련 패키지가 포함됩니다.docs-site/에는 문서 웹사이트가 포함됩니다.infra/self-host/에는 공급자 독립적인 배포 도구와 Hetzner Terraform 참조 구성이 포함됩니다.memory/에는 선택 사항인 팀 메모리 서비스가 포함됩니다.
사전 요구 사항
로컬 개발 환경을 설치하려면 Bun과 pgvector 확장이 설치된 Postgres 16 이상이 필요합니다. 표준 Postgres 컨테이너 이미지에는 pgvector가 포함되어 있지 않으므로, pgvector가 활성화된 적절한 이미지를 사용하세요.
제공된 데이터베이스 컨테이너 명령을 시작할 계획이라면 Docker도 사용할 수 있어야 합니다. 다음 단계는 useAgent 저장소 루트에서 실행하세요.
1단계: pgvector와 함께 Postgres 시작
호환되는 데이터베이스가 아직 없다면 Docker에서 다음과 같이 시작하세요.
docker run -d --name useagent-pg -p 5432:5432 \
-e POSTGRES_HOST_AUTH_METHOD=trust pgvector/pgvector:pg16
export DATABASE_URL=postgres://postgres@localhost:5432/postgres첫 번째 명령은 Postgres를 포트 5432에서 노출합니다. 두 번째 명령은 애플리케이션이 사용하는 연결 문자열을 설정합니다. trust 구성은 로컬 개발에 편리하지만, 프로덕션 환경에서는 적절히 보호된 데이터베이스 자격 증명을 사용해야 합니다.
2단계: 워크스페이스 종속성 설치
종속성은 공유 패키지, 백엔드 및 프런트엔드 워크스페이스에 각각 설치합니다.
for workspace in \
packages/agent-harness packages/artifact-workspace \
packages/agent-client packages/artifact-formats packages/conformance \
backend frontend; do
(cd "$workspace" && bun install)
done3단계: 백엔드와 프런트엔드 시작
별도의 터미널 세션을 열고 두 개발 프로세스를 시작하세요.
bun run dev:backendbun run dev:frontend백엔드는 포트 3201에서 API와 오케스트레이션 서비스를 제공합니다. 프런트엔드는 포트 3400에서 실행되며 /api/* 경로의 요청을 백엔드로 프록시합니다.
브라우저에서 http://localhost:3400을 열어 인터페이스에 접속합니다. 제공업체 및 샌드박스 구성은 다를 수 있으므로, 에이전트 엔진을 연결하거나 실행 환경을 프로비저닝할 때는 최신 useAgent 문서를 따르세요.
4단계: 코드베이스 검증
설치 후 또는 변경 사항을 제출하기 전에 저장소 전체 타입 검사기를 실행하세요.
bun run typecheck이 명령은 저장소의 모든 패키지를 검사하며, 공유 계약, 백엔드, 프런트엔드 간의 호환되지 않는 변경 사항을 발견하는 데 도움이 됩니다.
기본 사용법
에이전트 실행 생성
- 포트
3400에서 웹 인터페이스를 엽니다. - 에이전트 작성기를 사용해 필요한 완성 결과를 설명합니다.
- 실행을 시작하고 실시간 이벤트 타임라인을 확인합니다.
- 에이전트가 작업을 진행하는 동안 터미널, 브라우저, 데스크톱 또는 작업 공간 활동을 검사합니다.
- 파괴적인 도구 작업을 허용하기 전에 승인 카드를 검토합니다.
- 세션에서 반환된 완료된 산출물 또는 저장소 작업 결과를 수집합니다.
작업은 다음과 같이 구체적인 결과물을 중심으로 구성할 수 있습니다.
주제를 조사하고, 관련 출처를 인용한 뒤, 결과를 구조화된 보고서로 반환하세요.소프트웨어 작업에서는 예상되는 구현과 검증 방법을 정의하세요.
저장소에 요청된 변경 사항을 구현하고, 관련 테스트를 실행한 다음, 검토할 수 있도록 완료된 작업을 준비하세요.이는 특수한 명령 구문이 아니라 자연어 작업 예시입니다. 실행에 사용할 수 있는 정확한 도구는 구성된 엔진, 샌드박스, 지식 출처, 스킬 및 통합에 따라 달라집니다.
Slack을 통한 작업
기본 Slack 통합이 구성된 경우 사용자는 에이전트를 멘션하여 작업을 시작할 수 있습니다. 답변, 첨부 파일, 산출물 및 승인 요청은 Slack 스레드에 그대로 남습니다. 따라서 협업을 원래 채널에서 유지하면서 웹 인터페이스와 동일한 실행 경로를 사용할 수 있습니다.
조직 지식 및 스킬 사용
지식, 위키 콘텐츠 및 팀 메모리는 인용과 함께 조직 범위의 컨텍스트를 제공할 수 있습니다. 재사용 가능한 지침은 버전이 지정된 SKILL.md 스킬로 GitHub에서 가져올 수도 있습니다. useAgent는 이러한 스킬을 자동으로 다시 동기화하고 각 턴에 관련성이 높은 스킬의 순위를 정할 수 있습니다.
useAgent 셀프 호스팅
useAgent는 AWS, Google Cloud, Azure, Hetzner 또는 베어 메탈을 포함한 모든 Linux 호스트에서 실행할 수 있습니다. 저장소에는 제공업체와 무관한 배포 스크립트와 Terraform으로 구축된 원클릭 Hetzner 참조 호스트가 포함되어 있습니다.
Linux 호스트와 필요한 값을 준비한 후 저장소에서 배포 스크립트를 실행합니다.
SERVER_IP=<host-ip> PG_PASSWORD=... OPENROUTER_API_KEY=... \
infra/self-host/deploy-app.sh /path/to/this/repo프로비저닝 프로세스는 SSH를 통해 대상 시스템에 접속합니다. 축약된 예시를 완전한 보안 구성으로 간주하지 말고, 전체 프로덕션 가이드와 필요한 환경 세부 정보는 infra/self-host/README.md를 참고하세요.
샌드박스 런타임 선택
- Daytona: 모든 클라우드의 제어 플레인 호스트와 연결할 수 있는 관리형 샌드박스 서비스입니다. README에서는 가장 쉽게 시작할 수 있는 옵션으로 설명합니다.
- CubeSandbox: 자체 하드웨어에서 샌드박스를 운영하고 완전한 데이터 지역성을 필요로 하는 조직을 위한 셀프 호스팅 런타임입니다.
두 런타임 모두 동일한 샌드박스 계약을 기반으로 하므로, 제어 플레인은 핵심 실행 모델을 특정 샌드박스 제공업체에 종속시키지 않고 에이전트 작업을 오케스트레이션할 수 있습니다.
고급 운영 팁
- 릴리스 태그 고정: 프로젝트가 알파 단계이므로 알려진 태그를 고정하면 변경되는 API나 스키마로 인한 예기치 않은 중단을 줄일 수 있습니다.
- Postgres 보존: 이벤트 로그는 실행의 진실 공급원입니다. 이에 맞게 데이터베이스를 백업하고 운영하세요.
- 게이트웨이에 자격 증명 보관: 수명이 긴 통합 시크릿을 샌드박스에 복사하여 아키텍처를 우회하지 마세요.
- 승인을 신중하게 사용: 특히 Slack이나 일정에 의해 실행이 시작되는 경우 파괴적인 작업에 대한 휴먼 인 더 루프 제어를 활성화된 상태로 유지하세요.
- 운영 방식에 따라 샌드박스 선택: Daytona는 관리형 경로를 제공하고, CubeSandbox는 셀프 호스팅 실행과 데이터 지역성을 지원합니다.
- 타입 검사를 일관되게 실행: 공유 계약은 여러 작업 공간에 걸쳐 있으므로 패키지 간 변경 후
bun run typecheck를 사용하세요. - 프로덕션 배포 경로 검토: 전체 배포 지침은
infra/self-host/에 있으며, 추가 방식의 불변 컨테이너 릴리스 경로는docs/operations/immutable-releases.md에 문서화되어 있습니다. - 요청 흐름 검사: 저장소에는 더 심층적인 아키텍처 연구를 위한 대화형 다이어그램이
docs/architecture/request-flow.html에 포함되어 있습니다.
통합 및 제공 인터페이스
기본 Slack 및 GitHub 지원 외에도 이 플랫폼은 커넥터를 통해 Gmail, Linear, Notion 및 HubSpot을 제공합니다. OAuth는 브로커가 처리하며 토큰은 서버 측에서 봉인됩니다. 작업 공간 인터페이스에는 지식 기반, 팀 메모리, 스킬, 플레이북 및 예약된 자동화가 포함됩니다.
GitHub 통합은 앱 인증, 저장소 복제 및 풀 리퀘스트 워크플로를 지원합니다. 통합 종류와 관계없이 도구 호출은 신뢰 게이트웨이를 통과하므로 자격 증명이 에이전트 워크스테이션에 직접 노출되지 않습니다.
라이선스 고려 사항
useAgent는 GNU AGPL v3.0 전용 라이선스에 따라 배포됩니다. 해당 조건에 따라 사용, 수정 및 자체 호스팅할 수 있습니다. 독점 임베딩, OEM 또는 화이트 라벨 제품, AGPL 의무 없이 배포하거나 기타 라이선스 요구 사항이 있는 경우 상용 라이선스를 이용할 수 있습니다.
결론
useAgent는 여러 에이전트 엔진, 내구성 있는 Postgres 기반 실행, 격리된 Linux 샌드박스, 조직 컨텍스트, 보안 통합, 승인 및 편집 가능한 아티팩트를 하나의 자체 호스팅 플랫폼에 결합합니다. Bun과 pgvector로 로컬에서 시작하고, 타입 검사기로 모노레포를 검증한 다음, Linux 프로덕션 호스트로 이전할 때는 문서화된 자체 호스팅 절차를 사용하세요.