Vercel eve Tutorial: Build a Slack AI Agent with eve and Firecrawl

🖼️ 인포그래픽

Vercel eve Tutorial: Build a Slack AI Agent with eve and Firecrawl 내용을 설명하는 본문 이미지

🖼️ 4컷 인포그래픽

💡 한 줄 요약

Vercel의 파일시스템 중심 에이전트 프레임워크 eve에 Firecrawl 검색·스크래핑 도구를 결합해, 최신 웹 정보를 확인하고 출처와 함께 답하는 Slack AI 에이전트를 구축하는 방법을 설명한다.

📌 핵심 요약

eve는 에이전트의 모델, 지침, 도구, 스킬, 채널을 agent/ 디렉터리의 개별 파일로 정의하고 일반 Vercel 프로젝트처럼 배포하는 오픈소스 프레임워크다.
내구성 있는 세션, 샌드박스, 사람의 승인, 평가 기능이 기본 제공되며, Slack 인증은 Vercel Connect를 통해 처리되어 봇 토큰이나 서명 비밀을 직접 관리하지 않아도 된다.
예제 에이전트는 Firecrawl 기반 web_search로 실시간 웹을 검색하고, 정보가 부족하면 scrape_url로 단일 페이지의 전체 내용을 정제된 마크다운으로 읽는다.
연구 스킬은 권위 있는 출처 두세 개를 선택해 원문을 확인하고, 출처 간 내용을 교차 검증한 뒤 간결한 답변과 정확한 URL을 제시하도록 절차를 규정한다.
개발자는 Node.js 24 이상과 관련 계정을 준비한 뒤 프로젝트를 생성하고 환경 변수를 설정해 터미널 UI나 안정적인 HTTP 세션 API에서 에이전트를 로컬 테스트할 수 있다.

🧩 주요 포인트

기능별 파일 자동 발견 구조 → 별도 등록 파일 없이 도구와 채널을 추가할 수 있어 에이전트 구성과 유지보수가 단순해진다.
검색 결과 요약과 전체 페이지 스크래핑의 단계적 결합 → 시의성 있는 질문에 얇은 검색 조각만으로 답하지 않고 원문과 URL에 근거한 응답을 만들 수 있다.
직접 정의한 Firecrawl 도구와 키 없는 MCP 연결을 모두 제공 → 출력 형식·비용을 세밀하게 통제하는 방식과 빠르게 연결하는 저코드 방식 중 목적에 맞는 경로를 선택할 수 있다.

🧠 상세 정리

1. 기존 Slack 에이전트 구축의 복잡성과 eve의 접근

기존 방식으로 Slack AI 에이전트를 만들려면 서버를 준비하고 봇 토큰과 이벤트 웹훅을 설정한 뒤, 모델 호출과 도구 실행을 이어 주는 자체 에이전트 루프까지 구현해야 했다. eve는 이러한 구성을 파일 디렉터리로 압축해, 개발자가 에이전트의 역할과 기능을 파일로 선언하는 데 집중하도록 설계됐다. 내구성 있는 세션, 샌드박스, 사람의 승인, 평가, Slack 같은 채널 기능도 프레임워크에 포함된다. 이 글은 프로젝트 생성부터 타입이 지정된 도구와 스킬 추가, 로컬 실행, Slack 연결까지 이어지는 흐름을 소개하며, 특히 실시간 웹 정보를 근거로 답하게 만드는 Firecrawl 연동을 핵심 사례로 다룬다.

2. 파일시스템 중심의 에이전트 구조

eve는 Vercel이 공개한 오픈소스 프레임워크로, agent/ 아래의 파일들을 발견해 Vercel Functions에서 실행되는 애플리케이션으로 컴파일한다. 예제 구조에서 agent.ts는 사용할 모델을 지정하고, instructions.md는 에이전트의 정체성과 상시 적용 규칙을 담는다. tools/에는 웹 검색과 URL 스크래핑 도구가, skills/에는 다중 출처 조사 절차가, channels/에는 기본 HTTP 채널과 Slack 채널이 위치한다. 각 기능이 하나의 파일로 분리되므로 전체 에이전트의 역량을 디렉터리만 보고 파악할 수 있으며, 별도의 중앙 등록 파일을 계속 동기화할 필요도 없다.

3. Firecrawl 검색을 선택한 이유

eve에는 기본 web_search 도구가 있지만 로컬 실행기가 없고 모델 제공자가 실행하는 방식이어서, 결과가 얇은 검색 조각에 머물 수 있다고 글은 설명한다. 반면 Firecrawl 검색은 광고, 머리글, 바닥글 등을 제거한 언어 모델용 콘텐츠를 제공하고, 필요할 때 전체 페이지를 정제된 마크다운으로 가져올 수 있다. 자바스크립트 의존도가 높은 페이지와 봇 차단 마찰을 처리하며 도메인, 뉴스, 기간 필터와 JSON 스키마 기반 구조화 추출도 지원한다. 따라서 가벼운 일회성 조회에는 기본 도구를 사용할 수 있지만, 팀이 의존할 답변에서 근거와 인용이 필요하다면 Firecrawl을 통한 검색과 원문 확인이 더 적합하다는 것이 글의 판단이다.

4. 준비 사항과 기본 에이전트 생성

실습에는 eve가 런타임으로 고정한 Node.js 24 이상, Vercel 계정, 앱을 설치할 수 있는 Slack 작업 공간, Firecrawl API 키, 그리고 모델 자격 증명이 필요하다. npx eve@latest init eve-slack-agent 명령은 프로젝트 생성, 의존성 설치, Git 초기화, 개발 서버 시작을 한 번에 수행한다. 최소 구성에서 agent/agent.ts는 Vercel AI Gateway를 통해 사용할 모델을 지정하며, 예시는 처리량이 많은 Slack 봇을 위한 빠르고 저렴한 기본값으로 Haiku 4.5를 제시한다. 더 어려운 질문에는 상위 모델을 지정할 수 있고, 로컬에서 Anthropic 키를 직접 사용하는 경로도 설명하지만 Vercel에서는 OIDC를 활용하는 Gateway 방식이 더 단순한 선택으로 소개된다.

5. 상시 지침과 Firecrawl 웹 검색 도구

instructions.md는 에이전트를 공개 웹의 최신 정보를 조사하는 Slack 연구 도우미로 정의하고, 현재 사실·뉴스·가격·출시 정보·문서에 관한 질문에는 반드시 검색부터 수행하도록 지시한다. 검색 조각이 부족하면 전체 페이지를 읽고, 조사한 답변 끝에는 사용한 URL을 적으며, Slack 스레드에 맞게 간결하게 답하라는 규칙도 포함한다. 공유 클라이언트는 agent/lib/firecrawl.ts에서 환경 변수의 FIRECRAWL_API_KEY를 읽으므로 키가 모델에 전달되지 않는다. 이어 agent/tools/web_search.ts가 eve의 기본 검색 도구를 같은 파일명으로 재정의하고, 검색어·결과 수·웹 또는 뉴스 출처를 입력받아 제목, URL, 요약, 뉴스 날짜를 정돈된 결과로 반환한다.

6. 전체 페이지 스크래핑과 조사 스킬

scrape_url.ts는 검색 결과가 유망하지만 짧은 설명만으로 판단하기 어려울 때 단일 URL의 전체 내용을 마크다운으로 읽는 도구다. 이 도구는 URL 형식을 검증하고 Firecrawl의 스크래핑 기능으로 문서 제목과 본문을 가져오며, 반환 본문은 최대 1만 2천 자로 제한해 지나치게 큰 결과를 잘라 낸다. 별도의 research_a_topic.md 스킬은 철저한 답변, 비교, 다중 출처 요약이 필요한 경우 실행할 반복 절차를 정의한다. 절차는 집중된 검색어 사용, 최근 사건을 위한 뉴스 출처 지정, 권위 있는 URL 두세 개의 원문 확인, 출처 간 교차 검증, 불일치 공개, 간결한 핵심 bullet과 정확한 URL 제시 순서로 구성된다.

7. 키 없는 MCP 대안과 자동 기능 발견

직접 도구를 작성하지 않는 저코드 경로로는 agent/connections/firecrawl.ts에서 Firecrawl의 키 없는 MCP 엔드포인트를 연결하는 방법이 제시된다. 이 연결은 API 키 없이 검색, 페이지 스크래핑, 사이트 상호작용 기능과 월 1,000개의 무료 크레딧을 제공하며, eve는 서버가 공개한 스키마를 읽어 firecrawl__search, firecrawl__scrape 같은 도구를 자동 노출한다. 무료 범위를 넘어설 때는 auth.getToken 처리기를 통해 자체 키를 제공하면서 같은 연결을 유지할 수 있다. 다만 직접 정의한 도구는 출력 구조와 비용을 더 엄격하게 통제할 수 있으므로 본문은 이를 우선 경로로 제시하며, npx eve info로 디스크에서 발견된 도구·스킬·채널·일정을 확인할 수 있다고 설명한다.

8. 로컬 실행과 동작 확인

로컬 실행 단계에서는 예제 환경 파일을 .env.local로 복사한 뒤 Firecrawl API 키와 모델 자격 증명을 추가하고 npm run dev를 실행한다. 터미널 UI에서 최신 Node.js 안정 버전처럼 시의성이 있는 질문과 출처 인용 요청을 보내면, 에이전트가 web_search를 호출한 뒤 링크를 포함해 답하는 과정을 확인할 수 있다. 동일한 에이전트는 터미널에만 한정되지 않고 POST /eve/v1/session 형태의 안정적인 HTTP API로도 접근할 수 있으며, JSON 메시지를 보내 새 세션에서 질문할 수 있다. 제공된 원문은 이 API 예시 이후 문장이 중간에서 끝나므로, 그 뒤의 배포와 Slack 설치에 관한 구체적인 명령이나 화면 절차는 제시된 범위만으로 확인할 수 없다.

🧾 핵심 주장 / 시사점

eve의 핵심은 에이전트 기능을 코드베이스의 파일 배치와 일치시키는 데 있으며, 파일을 저장하면 자동으로 발견되는 구조가 기능 등록 누락과 구성 불일치를 줄인다.
검색과 스크래핑을 분리한 설계는 먼저 후보 출처를 좁힌 뒤 필요한 문서만 깊게 읽게 하므로, 최신성·근거·응답 크기를 함께 관리하는 조사 흐름을 만든다.
항상 적용되는 행동 원칙은 지침 파일에 두고 복잡한 다중 출처 절차는 필요할 때 불러오는 스킬로 분리함으로써, 기본 대화는 간결하게 유지하면서 조사 품질 기준은 반복 적용할 수 있다.

✅ 액션 아이템

eve의 agent/ 디렉터리에 Firecrawl 기반 web_search와 scrape_url 도구 파일을 두어 검색·스크래핑 경로를 정의한다.
연구 스킬에서 권위 있는 출처 두세 개를 고르고 교차 검증한 뒤 간결한 답변과 정확한 URL을 제시하도록 절차를 규정한다.
Slack 인증은 Vercel Connect로 두고 Node.js 24 이상 환경에서 터미널 UI나 HTTP 세션 API로 에이전트를 로컬 테스트한다.