vercel-labs/open-agents

Open Agents

Open Agents는 Vercel에서 백그라운드 코딩 에이전트를 구축하고 실행하기 위한 오픈소스 참조 앱입니다. 웹 UI, 에이전트 런타임, 샌드박스 오케스트레이션, 그리고 노트북을 켜지 않고도 프롬프트에서 코드 변경까지 이어주는 GitHub 통합을 포함합니다.

이 저장소는 블랙박스로 취급되지 않고 포크 및 수정되도록 설계되었습니다.

구성

Open Agents는 3계층 시스템입니다:

Web -> Agent workflow -> Sandbox VM

• 웹 앱은 인증, 세션, 채팅 및 스트리밍 UI를 처리합니다.
• 에이전트는 Vercel에서 지속성 워크플로우로 실행됩니다.
• 샌드박스는 실행 환경입니다: 파일 시스템, 셸, git, 개발 서버, 미리보기 포트.

핵심 아키텍처 결정: 에이전트는 샌드박스가 아닙니다

에이전트는 VM 내부에서 실행되지 않습니다. 샌드박스 외부에서 실행되며 파일 읽기, 편집, 검색, 셸 명령과 같은 도구를 통해 샌드박스와 상호작용합니다.

이 분리가 프로젝트의 주요 포인트입니다:

• 에이전트 실행이 단일 요청 수명 주기에 묶이지 않습니다.
• 샌드박스 수명 주기는 독립적으로 하이버네이트 및 재개될 수 있습니다.
• 모델/공급자 선택과 샌드박스 구현이 별도로 발전할 수 있습니다.
• VM은 제어 평면이 아닌 일반 실행 환경으로 유지됩니다.

현재 기능

• 파일, 검색, 셸, 작업, 스킬, 웹 도구를 갖춘 채팅 기반 코딩 에이전트
• Workflow SDK 기반 실행, 스트리밍 및 취소를 지원하는 지속성 다단계 실행
• 스냅샷 기반 재개가 가능한 격리된 Vercel 샌드박스
• 샌드박스 내에서 저장소 복제 및 브랜치 작업
• 성공적인 실행 후 선택적 자동 커밋, 푸시 및 PR 생성
• 읽기 전용 링크를 통한 세션 공유
• ElevenLabs 전사를 통한 선택적 음성 입력

런타임 참고 사항

현재 구현을 이해하는 데 중요한 몇 가지 세부 사항:

• 채팅 요청은 에이전트를 인라인으로 실행하는 대신 워크플로우 실행을 시작합니다.
• 각 에이전트 턴은 여러 지속성 워크플로우 단계에 걸쳐 계속될 수 있습니다.
• 활성 실행은 기존 워크플로우의 스트림에 다시 연결하여 재개할 수 있습니다.
• 샌드박스는 포트 3000, 5173, 4321, 8000을 노출하며, 선택적으로 구성된 기본 스냅샷을 사용할 수 있고 비활성 후 하이버네이트됩니다.
• 자동 커밋 및 자동 PR이 지원되지만, 항상 켜져 있는 동작이 아닌 선호도 기반 기능입니다.

환경 변수

전체 목록은 apps/web/.env.example을 참조하세요. 요약:

최소 런타임

POSTGRES_URL=
BETTER_AUTH_SECRET=

로그인에 필요 (Vercel OAuth)

NEXT_PUBLIC_VERCEL_APP_CLIENT_ID=
VERCEL_APP_CLIENT_SECRET=

GitHub 저장소 접근, 푸시 및 PR에 필요

NEXT_PUBLIC_GITHUB_CLIENT_ID=
GITHUB_CLIENT_SECRET=
GITHUB_APP_ID=
GITHUB_APP_PRIVATE_KEY=
NEXT_PUBLIC_GITHUB_APP_SLUG=
GITHUB_WEBHOOK_SECRET=

선택 사항

REDIS_URL=
KV_URL=
OPEN_AGENTS_RESOURCE_PROFILE=
VERCEL_PROJECT_PRODUCTION_URL=
NEXT_PUBLIC_VERCEL_PROJECT_PRODUCTION_URL=
VERCEL_SANDBOX_BASE_SNAPSHOT_ID=
ELEVENLABS_API_KEY=

• REDISURL / KVURL: 선택적 스킬 메타데이터 캐시 (설정되지 않으면 인메모리로 대체).
• OPENAGENTSRESOURCE_PROFILE: 선택적 배포 리소스 프로필. hobby로 설정하면 채팅 및 샌드박스 리소스에 Hobby 호환 기본값을 사용합니다. 설정하지 않으면 표준 동작.
• VERCELPROJECTPRODUCTIONURL / NEXTPUBLICVERCELPROJECTPRODUCTIONURL: 메타데이터 및 일부 콜백 동작을 위한 정식 프로덕션 URL.
• VERCELSANDBOXBASESNAPSHOTID: 새 샌드박스를 위한 선택적 기본 스냅샷. 설정하지 않으면 샌드박스는 Vercel의 표준 샌드박스 런타임에서 시작됩니다. 자신의 Vercel 범위에서 생성/접근 가능한 스냅샷을 사용하세요.
• ELEVENLABSAPIKEY: 음성 전사.

Vercel에 직접 배포하기

1. 이 저장소를 포크합니다.
2. 저장소를 Vercel로 가져옵니다. 위의 배포 버튼을 사용하면 Neon Postgres가 자동으로 프로비저닝됩니다.
3. 세션 서명을 위한 시크릿 생성:

   openssl rand -base64 32   # BETTER_AUTH_SECRET

1. Vercel 프로젝트 설정에 환경 변수 추가:

   POSTGRES_URL=
   BETTER_AUTH_SECRET=

1. 안정적인 프로덕션 URL을 얻기 위해 한 번 배포합니다.
2. 콜백 URL로 Vercel OAuth 앱 생성:

   https://YOUR_DOMAIN/api/auth/callback/vercel

1. 다음 환경 변수를 추가하고 재배포:

   NEXT_PUBLIC_VERCEL_APP_CLIENT_ID=
   VERCEL_APP_CLIENT_SECRET=

1. 전체 GitHub 지원 코딩 에이전트 워크플로우를 원한다면 GitHub App을 생성합니다:

• Homepage URL: https://YOUR_DOMAIN
• Callback URL: https://YOUR_DOMAIN/api/auth/callback/github
• Setup URL: https://YOUR_DOMAIN/api/github/app/callback

• NEXTPUBLICGITHUBCLIENTID 및 GITHUBCLIENTSECRET에 GitHub App의 Client ID와 Client Secret 사용
• 조직 설치가 원활하게 작동하도록 앱을 공개로 설정

GitHub App 설정에서:

1. GitHub App 환경 변수를 추가하고 재배포합니다.
2. 선택적으로 Redis/KV, Hobby 호환 리소스 기본값을 위한 OPENAGENTSRESOURCEPROFILE=hobby, 정식 프로덕션 URL 변수, 그리고 새 샌드박스가 사전 구성된 이미지에서 시작하도록 하려면 자신의 VERCELSANDBOXBASESNAPSHOT_ID를 추가합니다.

로컬 설정

1. 의존성 설치:

   corepack enable
   pnpm install

1. 로컬 env 파일 생성:

   cp apps/web/.env.example apps/web/.env

1. apps/web/.env에 필요한 값을 입력합니다.
2. 앱 시작:

   pnpm web

이미 연결된 Vercel 프로젝트가 있다면 vc env pull로 로컬에 환경 변수를 가져올 수 있습니다.

OAuth 및 통합 설정

Vercel OAuth

인증은 Better Auth로 처리되며 Vercel과 GitHub를 소셜 공급자로 사용합니다. 모든 인증 라우트는 /api/auth/[...all] catchall에서 제공됩니다.

Vercel OAuth 앱을 생성하고 다음 콜백을 사용하세요:

https://YOUR_DOMAIN/api/auth/callback/vercel

로컬 개발의 경우:

http://localhost:3000/api/auth/callback/vercel

그런 다음 설정:

NEXT_PUBLIC_VERCEL_APP_CLIENT_ID=...
VERCEL_APP_CLIENT_SECRET=...

GitHub App

별도의 GitHub OAuth 앱이 필요하지 않습니다. Open Agents는 GitHub App의 OAuth 자격 증명을 Better Auth 소셜 공급자로 사용하고, App의 설치 토큰을 저장소 접근에 사용합니다.

설치 기반 저장소 접근을 위한 GitHub App을 생성하고 다음을 구성하세요:

• Homepage URL: https://YOUR_DOMAIN
• Callback URL: https://YOUR_DOMAIN/api/auth/callback/github
• Setup URL: https://YOUR_DOMAIN/api/github/app/callback
• 조직 설치가 원활하게 작동하도록 앱을 공개로 설정

로컬 개발의 경우 Homepage URL로 http://localhost:3000, Callback URL로 http://localhost:3000/api/auth/callback/github, Setup URL로 http://localhost:3000/api/github/app/callback을 사용하세요.

그런 다음 설정:

NEXT_PUBLIC_GITHUB_CLIENT_ID=...   # GitHub App Client ID
GITHUB_CLIENT_SECRET=...           # GitHub App Client Secret
GITHUB_APP_ID=...
GITHUB_APP_PRIVATE_KEY=...
NEXT_PUBLIC_GITHUB_APP_SLUG=...
GITHUB_WEBHOOK_SECRET=...

GITHUBAPPPRIVATE_KEY는 이스케이프된 줄바꿈이 있는 PEM 내용 또는 base64로 인코딩된 PEM으로 저장할 수 있습니다.

유용한 명령어

pnpm web                    # dev 서버 실행
pnpm check                  # 린트 + 포맷 검사
pnpm fix                    # 린트 + 포맷 수정
pnpm typecheck              # 모든 패키지 타입체크
pnpm run ci                 # 전체 CI: 검사, 타입체크, 테스트, 마이그레이션 검사
pnpm sandbox:snapshot-base  # 샌드박스 기본 스냅샷 새로고침

저장소 구조

apps/web         Next.js 앱, 워크플로우, 인증, 채팅 UI
packages/agent   에이전트 구현, 도구, 서브에이전트, 스킬
packages/sandbox 샌드박스 추상화 및 Vercel 샌드박스 통합
packages/shared  공유 유틸리티