Gemini URL Context 사용법: 웹페이지 비교와 URL 조회 상태 확인

Gemini API에서 웹페이지 두 개를 비교하려면 요청에 URL과 비교 기준을 넣고 url_context 도구를 켭니다. 응답을 받은 뒤에는 비교 답변·출처·URL별 조회 상태를 함께 확인해야 합니다. 답변이 생성됐다는 사실만으로 두 페이지를 모두 읽었다고 판단하기는 어렵습니다.

기준일은 2026년 10월 16일입니다. Google 공식 문서의 Interactions API를 기준으로 설명하며, Gemini 앱의 화면 사용법은 다루지 않습니다.

이 글에서 사용하는 주요 용어 정의

용어정의

URL Context	지정한 웹페이지 내용을 모델의 응답 문맥으로 사용하는 도구입니다.
url_citation	응답의 특정 구간을 출처 URL과 연결하는 주석입니다.
url_context_result	URL 조회 시도의 결과를 담는 응답 단계입니다.

 

 

1. 같은 기준으로 비교하도록 요청하기

먼저 공개된 페이지 두 개를 고릅니다. 비교 항목을 지정하고, 원문에 없는 정보는 추정하지 말라고 요청하면 결과를 대조하기 쉽습니다. 예를 들어 두 기술 문서의 설치 조건·지원 기능·제한 사항을 같은 표에 정리하도록 할 수 있습니다.

아래는 공식 문서 기반 Python 예제이며 실행 미검증입니다. 인증을 준비한 환경에서 url_a, url_b를 실제 공개 페이지의 전체 주소로 바꿔 사용합니다. Google URL context 가이드의 예제는 SDK 2.0.0보다 새로운 버전과 gemini-3.8-flash를 사용합니다. 게시 직전 모델 접근 가능 여부와 SDK 조건을 다시 확인해야 합니다.

from google import genai

client = genai.Client()
url_a = "비교할 첫 번째 공개 페이지의 전체 주소"
url_b = "비교할 두 번째 공개 페이지의 전체 주소"

interaction = client.interactions.create(
    model="gemini-3.8-flash",
    input=(
        f"{url_a}와 {url_b}의 설치 조건, 지원 기능, 제한 사항을 "
        "한국어 표로 비교해 주세요. 각 항목에 근거 URL을 표시하고, "
        "원문에 없는 정보는 '확인 불가'로 적어 주세요."
    ),
    tools=[{"type": "url_context"}],
)

이 요청은 비교 방법을 보여주는 예제입니다. 실제 비교 표나 실행 성공 결과를 제시한 것은 아닙니다.

2. 비교 답변과 출처 읽기

Google URL context 가이드에 따르면 비교 답변은 model_output 단계의 텍스트에서 확인하며, url_citation 주석은 응답 구간과 출처 URL을 연결합니다. 중요한 비교 항목은 주석이 가리키는 원문과 대조하세요.

답변과 출처를 코드로 추출하려면 사용하는 Python SDK에서 해당 단계와 주석의 필드 구조를 먼저 확인해야 합니다. 여기서는 세부 필드 경로를 검증하지 않았으므로 답변·출처 추출 코드는 제공하지 않습니다.

3. URL별 조회 상태 확인하기

조회 여부는 url_context_result 단계의 result 배열에서 확인합니다. Google Interactions API 스키마에 정의된 상태는 다음과 같습니다.

status문서상 의미확인 후 할 일

success	조회 성공	핵심 비교 내용과 원문을 대조합니다.
error	오류로 조회 실패	상태값만으로 원인을 단정하지 않습니다.
paywall	유료벽으로 실패	대체 공개 자료를 찾습니다.
unsafe	안전성 문제로 실패	해당 페이지를 읽었다고 전제하지 않습니다.

다음은 조회 결과를 출력하는 실행 미검증 예제입니다. 스키마에서 URL과 상태는 선택 필드이므로, 누락된 값을 성공으로 처리하지 않도록 작성했습니다.

found = False
for step in interaction.steps:
    if step.type == "url_context_result":
        found = True
        for item in (step.result or []):
            print(item.url or "주소 없음",
                  item.status or "상태 미확인")
if not found:
    print("URL 조회 결과 단계 없음")

결과 단계가 있어도 배열이 비었거나 입력한 주소의 결과를 찾을 수 없다면 조회 여부는 미확인으로 남기는 편이 좋습니다. 이는 누락값에 대비한 구현 제안입니다. success도 비교 내용의 정확성이나 페이지 전체의 추출을 보증하는 값으로 해석하지 마세요.

비교 결과를 사용하기 전에

Google 가이드는 내부 인덱스 캐시를 먼저 확인하고, 자료가 없으면 실시간 조회한다고 설명합니다. 따라서 결과를 항상 방금 읽은 최신 원문으로 간주해서는 안 됩니다. 로그인·유료벽 페이지도 비교 대상으로 피해야 합니다.

우선 공개 문서 두 개로 요청한 뒤, 비교 표의 핵심 항목 하나를 출처 원문과 맞춰 보세요. 두 URL의 조회 상태까지 확인하면 빠진 자료를 근거로 판단하는 일을 줄일 수 있습니다.

참고 링크

• Google AI for Developers — URL context
• Google AI for Developers — Gemini Interactions API