AI Gateway Browserbase: 검색과 본문 조회를 나누고 옵션별 비용을 고정하기

웹 자료를 읽는 에이전트에서 “검색 도구를 붙였다”는 말은 충분하지 않다. 검색 결과의 제목을 받았는지, 실제 페이지 본문을 읽었는지, 추출 형식과 프록시를 누가 선택했는지에 따라 증거의 범위와 비용이 달라진다. 모델만 교체하고 도구 설정을 그대로 쓰더라도 요청 횟수와 옵션까지 같아지는 것은 아니다. 이번 변화의 실용적인 지점은 모델 공통 도구를 확보하는 데서 끝나지 않고, 검색과 읽기의 역할을 분리해 운영자가 비용 조건을 명시할 수 있다는 데 있다.

Vercel은 2026년 9월 30일 공개한 AI Gateway 변경 공지에서 Browserbase Search와 Fetch를 제공한다고 밝혔다. 도구 호출을 지원하는 모델에 웹 검색과 페이지 조회를 붙이고, 모델을 바꿀 때 같은 도구 구성을 유지할 수 있다는 설명이다. 단일 AI Gateway API 키를 사용하며, 전용 helper의 문서상 최소 버전은 AI SDK 7.0.116 이상이다. 이것은 최신 SDK 버전을 별도로 조사한 값도, 도구 호출을 지원하지 않는 모델까지 동작한다는 보장도 아니다.

이 글은 2026년 10월 2일 한국시간에 보존한 공지와 공식 문서의 해당 절을 해설한다. 가격과 동작 설명은 확인 당시 문서에 묶여 있고, 실제 Browserbase API나 모델을 실행하지 않았다. 읽기 품질, 속도, 사이트 접근 성공률을 측정한 사용 후기로 받아들이면 안 된다.

1. Search는 후보를 찾고 Fetch는 이미 아는 주소를 읽는다

Search는 브라우저 세션을 열지 않고 결과의 제목·URL·메타데이터를 반환한다. 따라서 관련 페이지를 고르는 데 쓰되 검색 결과가 곧 원문 전체라고 취급해서는 안 된다. Fetch는 모델이 이미 가진 URL의 내용을 가져온다. 공식 문서는 JavaScript 실행이나 브라우저 조작이 필요 없는 페이지에 쓰는 가벼운 조회 경로라고 설명한다. raw 응답 본문, Markdown, JSON Schema에 맞춘 구조화 JSON을 선택할 수 있다.

검색 결과는 원문 검증이 아니다. 이미 아는 URL은 바로 조회하며 Fetch의 비JavaScript·비브라우저 조작 범위를 지킨다. 공식 문서의 원본 도식으로 실제 화면이 아니다. 출처: vercel.com/docs/ai-gateway/models-and-providers/web-search.

예를 들어 발표 날짜를 확인하려면 Search로 공지 후보를 찾은 뒤 공식 URL을 선택하고 Fetch로 그 페이지를 읽는 흐름이 맞다. 반대로 입력에 공식 URL이 이미 있으면 검색부터 반복할 이유가 없다. 또한 로그인 후 버튼을 눌러야 나오거나 JavaScript 실행에 의존하는 내용은 이 Fetch 설명만으로 수집 가능하다고 결론 내리지 않는다. “브라우저 기반 제품의 도구”와 “브라우저를 실제로 조작하는 도구”는 다른 의미다.

Search의 numResults는 반환 결과 수의 상한으로 1–25이며 기본값은 10이다. 모델이 공급하는 query는 1–200 문자여야 한다. 결과를 적게 달라고 요청하는 것은 후보 검토량을 줄이는 선택이지, 검색 요청 한 번의 문서상 가격을 낮추는 선택이 아니다. URL 하나를 선택해 본문에서 주장 근거를 찾는 검증 단계는 별도로 남는다.

2. 가격의 분모는 결과가 아니라 도구 요청이다

공식 문서에서 Search는 결과 개수와 무관하게 1,000 요청당 7달러다. Fetch는 기본 raw 조회가 1,000 요청당 1달러이고, 프록시 사용에 3달러, Markdown 또는 JSON 추출에 3달러가 각각 추가된다. 프록시와 추출을 함께 쓰면 문서상 합계는 1,000 요청당 7달러다. 아래 비교는 같은 요청 수의 단가만 보여 주며 모델 토큰 요금이나 전체 업무 비용을 포함하지 않는다.

분모는 1,000 요청이며 기본 1달러에 프록시·추출이 각각 3달러 추가된다. 막대는 단가에 비례한다. 확인 당시 문서 가격이며 모델 요금·전체 작업 비용·실제 청구서가 아니다. 출처: vercel.com/docs/ai-gateway/models-and-providers/web-search.

경로	프록시	표현 형식	문서상 단가 / 1,000 요청	읽을 때 주의할 점
Search	Fetch 옵션 아님	제목·URL·메타데이터	7달러	반환 결과 수와 무관, 본문 검증은 별도
Fetch 기본	사용 안 함	raw	1달러	원 응답 본문이며 읽기 좋은 텍스트와 같지 않을 수 있음
Fetch 추출	사용 안 함	markdown 또는 json	기본 1달러 + 추출 3달러	추출 표현과 원 응답은 다른 증거
Fetch 프록시	사용함	raw	기본 1달러 + 프록시 3달러	프록시가 모든 접근 실패를 해결하는 것은 아님
Fetch 프록시·추출	사용함	markdown 또는 json	합계 7달러	두 가산 옵션 모두 적용

Search와 프록시·추출 Fetch의 표기 단가가 같아도 서로 대체하는 도구는 아니다. 하나는 주소 후보를 찾고 다른 하나는 주소의 내용을 읽는다. 에이전트 한 작업에 검색과 여러 페이지 조회가 들어가면 각각의 요청을 집계해야 한다. 재시도가 반복되거나 모델이 여러 페이지를 읽으면 전체 사용량은 달라진다. 따라서 단가 표를 “정답 하나를 만드는 비용”으로 환산하면 안 된다.

가산 요금은 실제 upstream으로 전달된 옵션과 Gateway usage metadata를 기준으로 청구된다는 것이 문서의 설명이다. 프롬프트에서 raw를 요청했다는 사실만으로 청구 옵션이 고정됐다고 단정하지 말고, helper 설정과 실제 사용 기록을 구분해서 살펴보는 편이 낫다. 이 글의 표는 청구서나 실행 로그가 아니라 공식 가격 구조의 정리다.

3. 기본값을 아는 것과 옵션을 고정하는 것은 다르다

Fetch에서 format이 생략되면 Browserbase는 raw를 기본으로 사용한다. allowRedirects, proxies, allowInsecureSsl의 기본값은 모두 false다. 다만 모델은 URL과 함께 format, redirect, proxies 옵션을 제안할 수 있다. 개발자가 browserbaseFetch() helper에 값을 설정하면 그 설정이 모델이 만든 값보다 우선한다. 값이 비어 있을 때의 기본 동작과, 모델 제안을 덮어쓰는 명시적 설정은 구분해야 한다.

개발자 helper 설정은 모델 제안을 덮어쓰며 schema와 allowInsecureSsl은 개발자 전용이다. format·proxies 고정은 전체 예산 상한이나 보안 전면 해결을 뜻하지 않는다. 출처: vercel.com/docs/ai-gateway/models-and-providers/web-search.

독자에게 필요한 규칙은 간단하다. format과 proxies는 각각 단가를 바꾸므로, 사용할 표현 형식과 프록시 허용 여부를 함께 결정한다. proxies만 false로 고정하면 모델이 추출 형식을 선택할 여지는 남는다. format만 raw로 고정하면 프록시 선택이 여전히 단가에 영향을 줄 수 있다. 둘을 정책에 맞게 명시하면 해당 옵션 조합의 단가를 관리하기 쉽지만, 요청 횟수·모델 요금·다른 도구 사용까지 제한하는 전체 예산 하드 상한은 아니다.

schema와 allowInsecureSsl은 개발자 전용 설정이다. 공식 문서는 모델이 이 값을 설정할 수 없고, 프롬프트 인젝션으로 들어온 해당 값은 Fetch 실행 전에 버려진다고 설명한다. 이것을 페이지 전체의 프롬프트 인젝션이 해결됐다거나, URL·본문·출력의 신뢰 검사가 필요 없다는 뜻으로 확장하지 않는다. 특히 인증서 검증을 건너뛰는 설정을 수집 오류의 일반적인 해결책처럼 권장할 근거는 없다.

4. 요청 목적별 판단표: 싸게 읽기보다 필요한 증거를 먼저 고른다

URL을 이미 알고 있다면 Search를 생략하고, 필요한 표현 형식부터 결정한 뒤 Fetch 옵션을 고정한다. 아래 표는 공식 helper의 동작 설명에 운영 판단을 덧붙인 독자용 선택 도구다. 자동으로 비용을 최적화하는 기능이 제공된다는 주장이 아니다.

지금 필요한 것	선택할 경로	명시할 조건	보류하거나 별도로 확인할 것
관련 공식 페이지의 주소 후보	Search	필요한 결과 상한 numResults	후보 제목만으로 사실 검증을 완료하지 않음
이미 아는 URL의 원 응답 보존	Fetch raw	format: 'raw', 프록시 정책 명시	응답에 원하는 본문이 실제 있는지 확인
페이지를 읽기 쉬운 텍스트로 전달	Fetch markdown	추출 허용, 프록시 정책 명시	변환에서 필요한 문맥이 빠졌는지 원 응답과 구분
정해진 필드를 구조화해 후속 처리	Fetch json	개발자가 JSON Schema 제공	schema 누락과 필드 추출 오류를 별도로 검사
로그인·JavaScript·상호작용이 필수	이 경로만으로 결정하지 않음	필요한 접근 방식과 권한부터 확인	Fetch의 지원 범위를 넘는다고 가정하지 않음

필요한 증거부터 고르는 편집자 판단 흐름이다. JSON에는 schema가 필요하고 raw 재시도는 출력 종류를 바꾼다. 동적 페이지·로그인·조작 지원은 별도 확인하며 실행 결과를 제시한 그림이 아니다. 출처: vercel.com/docs/ai-gateway/models-and-providers/web-search.

JSON 추출에서는 schema가 빠져도 Gateway validation을 통과할 수 있지만 Browserbase에서는 오류가 난다고 문서가 경고한다. 따라서 Gateway에서 입력 검사를 통과했다는 것과 upstream에서 원하는 구조가 생성됐다는 것은 별개다. 개발자가 기대하는 필드·타입·필수 여부를 정하고, 성공으로 표시된 결과에도 업무에 필요한 값이 있는지 확인하는 설계가 필요하다.

추출을 사용할 수 없거나 할당량이 소진된 상황에 대해 문서는 raw로 재시도하고 schema를 생략하는 경로를 안내한다. 그러나 raw로 바꾸면 출력 표현이 달라진다. JSON 필드를 받던 후속 처리에 raw 문자열을 그대로 넘기고 “복구 성공”이라고 기록하면 안 된다. 출력 종류를 명시하고, 원문 읽기 또는 별도의 변환 단계가 필요한지 다시 판단해야 한다. 보존한 텍스트에서는 일부 오류 코드가 불완전하게 추출돼 전체 오류 코드 목록을 주장하지 않았다.

5. 모델을 교체해도 유지할 것과 다시 확인할 것

같은 도구 구성을 유지할 수 있다는 장점은 재사용 경계를 분명히 할 때 의미가 있다. 개발자가 정한 format·proxies·schema 정책은 유지하되 새 모델이 어떤 URL을 고르고 몇 번 호출하는지, 필요한 주장 근거를 실제로 읽는지는 다시 확인해야 한다. 공통 도구를 쓰는 것만으로 모델 간 품질·도구 선택·총비용이 동일해지지는 않는다. API와 제공자별 도구 표현 형식도 다를 수 있으므로 다른 인터페이스에 그대로 복사해 쓸 수 있다고 약속하지 않는다.

운영 기록에는 선택한 URL, 실제 옵션, 요청 결과의 표현 형식, 사용량 메타데이터, 재시도 이유를 연결해 두는 것이 유용하다. 이것은 이 글의 설계 제안이며 문서에 나온 로그를 여기서 실제 수집한 것은 아니다. 요청 실패가 반복될 때 프록시와 추출을 무조건 모두 켜는 대신, 원인을 확인하고 필요한 옵션만 승인하는 편이 비용과 증거 범위를 설명하기 쉽다. 형식을 바꾼 대체 결과가 원래 업무를 충족하지 못하면 결과를 보류해야 한다.

이 판단표는 공식 문서를 운영 선택으로 재구성한 편집자 분석이며, 실제 API 실행이나 독립 성능 검증 결과가 아니다. AI를 활용해 공개 자료의 해설과 원본 도식을 작성했으며 공식 화면·실제 청구서·제품 성능 측정치를 만들어 제시하지 않았다.

출처와 확인 범위

• Vercel 변경 공지: AI Gateway adds Browserbase Search and Fetch tools: 도구 호출 지원 모델, 단일 키, helper 최소 SDK 버전. 공개 시각과 수정 시각은 보존 메타데이터에서 별도로 확인했다.
• Vercel 공식 문서: Web search: Using Browserbase Search / Fetch와 각 parameters 절. 역할·단가·옵션 우선순위·schema 경계의 근거이며 2026년 10월 2일 한국시간 확인본을 사용했다.

내부 관련 링크는 이번 글에 추가하지 않았다. 기존 CI 비용 감사·인증 경계 글은 선정 당시 중복 점검에 사용했지만, 이 단계에서 현재 공개 URL과 해당 본문의 연결을 검증하지 않아 주소를 추측하거나 무관한 글을 강제로 붙이지 않았다.