Firecrawl Universal Scrape와 Alexandria: 도구 탐색부터 데이터 호출까지

Firecrawl Universal Scrape는 원래 쓰던 /scrape로 웹 페이지와 파일뿐 아니라, 지원되는 외부 제공자의 데이터까지 불러오는 기능입니다. Alexandria는 필요한 도구를 찾고 그 도구의 입력 조건과 가격을 확인하는 라이브러리예요. 여기서 고른 도구 가운데 실행이 지원되는 기능을 Universal Scrape로 호출하는 구조입니다.

시작하기 전에 하나만 먼저 정리해 두면 나머지가 쉬워집니다. 읽을 URL을 이미 알고 있는지, 아니면 필요한 데이터가 무엇인지만 알고 있는지예요.

제품 페이지 주소가 손에 있다면 그 URL을 보내 내용을 읽으면 됩니다. 반대로 특정 주제의 팟캐스트 데이터가 필요하다면, 그걸 제공하는 도구부터 찾아야 하죠. 둘 다 같은 API를 쓰지만 URL 요청과 제공자 호출은 입력 구조부터 다릅니다. 이 차이를 놓치면 도구 탐색 결과를 실제 데이터로 착각하기 쉽고, 실행 요청도 엉뚱하게 짜게 됩니다.

URL을 보내는 요청과 제공자를 부르는 요청

URL 기반 요청에는 읽을 주소를 넣습니다. 명시적 Alexandria 요청은 생김새가 달라서, provider에 제공자를, capability에 실행할 기능을, options에 그 기능이 받는 입력값을 지정해요. 페이지 주소 없이도 호출할 수 있는 대신, 어떤 입력이 필요한지는 도구마다 따로 확인해야 합니다. 그리고 여기서 가장 많이 헷갈리는 부분이 있는데, 도구 검색은 호출할 기능을 찾는 단계일 뿐이에요. 검색만 해서는 제공자 데이터가 돌아오지 않습니다.

URL을 보냈다고 늘 페이지 본문이 오는 것도 아닙니다.

예를 들어 LinkedIn 프로필 URL을 보내면, 조직에 설정된 외부 제공자를 차례로 조회해서 먼저 찾은 레코드를 반환할 수 있어요. 이런 경우라면 응답의 metadata.provider부터 확인하길 권합니다. 데이터가 어디서 왔고 비용이 얼마나 드는지 알아야 그다음 처리 방식을 정할 수 있으니까요.

정리하면 URL로 접근할 수 있는 문서는 /scrape로, URL이 없는 로컬 파일은 /parse로 보내면 됩니다.

도구를 찾고, 입력과 가격을 보고, 실행하기까지

상황을 하나 잡아 보겠습니다. 제품을 조사하면서 웹페이지의 제품 설명과 Particle에서 검색한 관련 팟캐스트 에피소드를 함께 모으려는 경우예요. 두 자료는 각각 따로 호출하고, 합치는 건 조사 단계에서 합니다. 도구 탐색에서 제공자 실행까지는 아래 순서로 이어집니다.

1. /search의 sources에 alexandria를 포함해 도구를 찾습니다. 웹 검색도 함께 요청하면 web과 tools 결과를 받을 수 있습니다.
2. findTools 또는 find_tools로 후보 도구의 options, response, 실행 가격을 확인합니다.
3. /v2/scrape의 alexandria 객체에 제공자·기능·입력값을 넣어 실행합니다.

2단계를 건너뛰고 바로 실행하고 싶어지는데, 입력 규격을 모르면 3단계의 options를 채울 수가 없어요. 그래서 이 순서를 지키는 편이 결국 빠릅니다.

Particle 호출의 요청 본문은 아래처럼 쓸 수 있습니다. episodeOptions에는 앞 단계에서 확인한 입력 규격에 맞춰 검색 조건을 넣으면 돼요.

const body = {
  alexandria: {
    provider: "particle",
    capability: "podcasts/episodes/search",
    options: episodeOptions
  }
};

제품 설명은 이것과 별개로 URL 기반 scrape 요청을 보내 읽습니다. 두 응답을 합치면 웹페이지 설명과 관련 에피소드 검색 결과를 한자리에서 검토할 수 있습니다.

응답에서 데이터를 꺼내는 위치도 꼭 짚어 두세요. SDK에서는 result.alexandria[0].data로 접근하지만, 원시 HTTP 응답에는 바깥쪽에 data 객체가 한 겹 더 있어요. SDK 예제의 경로를 HTTP 응답 처리 코드에 그대로 옮기면 값을 놓칠 수 있습니다. 연동할 때는 Alexandria 공식 문서의 응답 구조를 한 번 대조해 보는 게 좋습니다.

어디까지 실행되는지, 요청과 재시도는 어떻게 다루는지

Alexandria 카탈로그에 등록된 도구와 Universal Scrape에서 실제로 실행할 수 있는 도구는 같은 목록이 아닙니다. 그러니 필요한 기능이 실행을 지원하는지부터 보세요. 도구 탐색 자체는 무료지만, 같이 요청한 웹 검색과 제공자 실행에는 각각 비용이 붙어요.

명시적 Alexandria 호출은 한 요청에 최대 10개까지 배열로 보낼 수 있고, URL이나 다른 scrape 옵션과 섞어 쓸 수는 없습니다. 요청 전체가 성공으로 끝나도 개별 결과 안에 오류가 담겨 있을 수 있어서, 항목마다 확인하는 처리가 필요합니다.

재시도에서도 요청 유형을 먼저 가려야 해요. 같은 본문과 x-request-id를 보내면 완료된 결과를 재사용하는 규칙은 명시적 Alexandria 호출에 적용됩니다. 제공자가 처리하는 URL scrape에도 똑같이 적용될 거라고 가정하면 안 됩니다.

THIRD_PARTY_DATA_TERMS_REQUIRED 오류를 받았다면 requiresAction.url을 확인해 조직 관리자가 약관에 동의하는 절차로 넘기면 됩니다. 에이전트가 대신 동의하게 하려면 사용자의 명시적 승인이 있어야 해요. 여기까지 설명한 조건은 2026년 10월 20일 문서 기준입니다. 실제로 연동할 때는 Scrape 공식 문서와 호출 응답으로 지원 범위와 동작을 확인하세요.