Vercel 템플릿으로 Python 에이전트 앱을 만든다

Vercel의 eve-agent-python-template은 웹 채팅에서 공유 작업 목록을 관리하고 Python 도구를 실행하는 에이전트 앱의 시작점이다. eve, Next.js, FastAPI를 함께 사용하며, Vercel에 배포하거나 로컬에서 실행할 수 있다.

기능과 구성

채팅에서 작업 추가·완료·삭제를 요청하면 에이전트가 작업 페이지와 같은 FastAPI 엔드포인트를 호출한다. 채팅과 페이지에서 바꾼 내용은 서로 반영된다. 통계 계산과 텍스트 분석은 백엔드에서 Python 코드로 처리한다. 작업 삭제 전에는 승인을 요청한다.

에이전트는 agent/, 웹 앱은 apps/web/, FastAPI 백엔드는 apps/api/에 있다. 세 구성 요소는 Vercel Services를 통해 한 프로젝트에서 함께 배포된다. 백엔드에는 공개 경로가 없어 브라우저는 웹 앱을 통해서만 백엔드에 접근한다. Backend 페이지에서는 Python과 FastAPI 버전을 확인하고 통계를 계산할 수 있으며, API 페이지에서는 백엔드가 OpenAPI 문서에 공개한 엔드포인트를 볼 수 있다.

배포와 접근 설정

Vercel 프로젝트 설정을 진행하면 Git 계정에 저장소와 Vercel 프로젝트가 만들어진다. 앱 접근에 사용할 EVE_CHAT_PASSWORD를 설정하고 Neon 연동으로 Postgres 데이터베이스를 구성해야 한다. Neon 연동은 작업 저장에 쓰이는 DATABASE_URL 환경 변수를 설정한다. 배포가 끝나면 배포 URL에서 비밀번호를 입력하고 채팅에 작업 추가를 요청한 뒤 Tasks 페이지에서 확인할 수 있다.

비밀번호를 아는 방문자는 모두 같은 작업 목록을 공유하며 서로를 동일한 신뢰 수준으로 취급한다. 따라서 서로의 채팅과 작업을 볼 수 있는 사람에게만 비밀번호를 공유해야 한다. 템플릿은 길고 무작위인 비밀번호를 선택하도록 안내하며, Clerk나 Better Auth 등 다른 인증 제공자로 바꾸는 방법은 맞춤 설정 안내에 설명돼 있다.

로컬 실행

Node.js 24, pnpm, 백엔드 Python 패키지를 설치하는 uv, Vercel CLI가 필요하다. 저장소를 복제한 뒤 다음 명령을 실행한다.

pnpm install
vercel link
vercel env pull .env.local
pnpm dev:all

vercel link에서 배포된 프로젝트를 선택한다. vercel env pull .env.local은 모델 호출에 쓰이는 Vercel AI Gateway 토큰을 포함해 프로젝트의 개발 환경 변수를 가져온다. pnpm dev:all은 vercel dev로 웹 앱, 에이전트, 백엔드를 함께 실행한다. EVE_CHAT_PASSWORD가 설정되지 않으면 비밀번호 없이 앱이 열리고, DATABASE_URL이 없으면 작업은 apps/api/.data/dev.sqlite3의 SQLite 파일에 저장된다. 터미널에서 에이전트와 대화하려면 별도 터미널 두 곳에서 pnpm dev:api와 pnpm dev:eve를 실행한다.

배포 전에는 다음 명령으로 유형 검사, 테스트, API 코드 검사, 빌드를 확인한다. pnpm test는 백엔드 테스트를 pytest로 실행하고 pnpm lint:api는 Python 코드를 Ruff로 검사한다. 검사가 통과하면 vercel deploy --prod로 배포할 수 있다.

이 템플릿은 에이전트의 말투와 도구, 백엔드 엔드포인트, 채팅 화면과 결과 표시 구성 요소를 바꿀 수 있다. 상세한 파일 위치와 추가 방법은 저장소의 맞춤 설정 안내에서 확인할 수 있다. 저장소와 문서는 eve Python 에이전트 템플릿, eve 문서, Next.js 문서, FastAPI 문서, Vercel Services, Vercel Sandbox를 참고하면 된다.