AIREITER코딩 에이전트가 Google 개발자 페이지를 직접 스크래핑하는 일은 어렵지 않다. 다만 페이지 구조 추적, 문서 탐색, 중복 제거, 출처 관리까지 모두 에이전트 측 책임이 된다. Google Developer Knowledge API는 이 작업을 문서화된 인터페이스 뒤로 옮긴다. 에이전트에 최신 Google 공식 문서를 감사 가능한 컨텍스트로 제공해야 한다면 기본 선택지로 더 적합하다. 단, 대상은 전체 Google 개발자 웹이 아니라 선별된 코퍼스라는 점은 분명히 알아야 한다.
이 API는 실행 도구가 아니라 문서 조회 도구다
Google Developer Knowledge API는 Google의 공개 개발자 문서를 기계가 읽을 수 있는 형태로 제공한다. Google은 REST 레퍼런스에서 문서 검색, 전체 문서 조회, 일괄 조회, 근거 기반 답변 기능을 안내한다.
이 서비스는 애플리케이션이나 에이전트에 읽기 전용 컨텍스트를 제공한다. 비공개 Cloud 프로젝트에 접근하게 해주지도 않고, IAM 변경을 승인하거나 코드를 배포하지도 않으며, 생성된 명령어의 안전성을 검증하지도 않는다. 쓰기 작업을 수행하려면 에이전트에 별도의 자격 증명과 정책 게이트가 여전히 필요하다.
코퍼스의 범위도 중요하다. Google의 API 문서가 다루는 것은 일반 웹이 아니라 공개 개발자 문서다. 임의의 GitHub 저장소, Stack Overflow, 사내 런북, 서드파티 라이브러리를 검색하는 용도로 대체할 수는 없다. 또한 반환되는 Markdown은 원본 HTML에서 생성되므로, 렌더링된 페이지를 바이트 단위까지 그대로 복제한 결과물로 보면 안 된다고 Google은 밝힌다.
현재 제공 여부와 동작 방식은 공식 API 레퍼런스 및 릴리스 노트에서 확인하는 것이 좋다.
Google Developer Knowledge API가 제공하는 기능
REST API 표면은 작아서 에이전트 정책에 직접 반영하기 좋다.
| 작업 | 반환 내용 | 적합한 용도 |
|---|---|---|
SearchDocumentChunks | 일치하는 청크와 상위 문서 리소스 | 근거와 후보 문서 찾기 |
GetDocument | Markdown 형식의 완전한 문서 하나 | 에이전트에 페이지 전후 맥락 제공 |
BatchGetDocuments | 완전한 문서 여러 개 | 관련 페이지 비교 또는 로컬 캐시 예열 |
AnswerQuery | 근거 참조가 포함된 답변 | 범위가 정해진 문서 질의에 답변 |
검색 결과는 전체 페이지가 아니라 청크다. 결과의 parent 리소스는 GetDocument 또는 BatchGetDocuments로 이어지는 연결점이다. 견고한 클라이언트라면 페이지를 가져오기 전에 상위 리소스 기준으로 중복 청크를 묶어야 한다. 그렇지 않으면 문서 하나가 검색 슬롯을 여러 개 차지하면서도 추가 맥락은 거의 제공하지 못할 수 있다.
일반적인 리소스 이름은 문서 리소스 형식을 따른다.
documents/docs.cloud.google.com/storage/docs/creating-buckets이 리소스 이름 패턴은 검색 응답을 처리할 때 유용하지만, 에이전트는 기억에 의존해 이름을 조합하기보다 서비스가 반환한 정확한 parent 값을 우선 사용해야 한다.
검색 모드는 서로 다른 근거 수준을 제공한다
SearchDocumentChunks는 근거 우선 모드다. 정확한 플래그, 파라미터, 권한, 버전 관련 참고 사항, 코드 조각이 필요할 때 사용한다. 호출 측은 청크 내용을 직접 확인하고 문서 URI를 보존한 뒤, 전체 페이지를 가져올지 판단할 수 있다.
GetDocument와 BatchGetDocuments는 맥락 확보용 모드다. 답변이 사전 요구 사항, 경고, 마이그레이션 안내, 또는 하나의 청크만으로는 빠질 수 있는 인접 섹션에 좌우된다면 검색 후 이 기능을 사용한다. 설계 질문이 여러 공식 문서에 걸칠 때는 일괄 조회가 유용하다.
AnswerQuery는 종합 모드다. 코퍼스에 근거해 답해야 하는 “이 조건에 맞는 현재 Google Cloud 옵션은 무엇인가?” 같은 범위가 분명한 질문에 알맞다. 그렇다고 매끄러운 답변을 참조 자료 확인 없이 받아들여도 된다는 뜻은 아니다. 위험도가 높은 코드 변경이라면 검색 후 전체 문서를 조회하는 방식이 에이전트의 근거 추적을 더 쉽게 만든다.
인증 방식은 호출 주체에 맞춰 선택한다
실용적인 인증 패턴은 세 가지지만, 모두 같은 호출 주체를 위한 것은 아니다.
| 호출 주체 | 권장 시작점 | 이유 |
|---|---|---|
| 로컬 curl 또는 빠른 프로토타입 | 제한된 API 키 | 첫 요청을 보내기까지 가장 빠른 방법 |
| 백엔드, 워커 또는 Python 클라이언트 | Application Default Credentials (ADC) | 자격 증명을 소스 코드가 아닌 런타임 환경에 보관 |
| 대화형 MCP 클라이언트 | 호스트가 지원하면 OAuth, 아니면 제한된 키 | 사용자 도구에 장기 키 하나를 배포하지 않아도 됨 |
빠르게 시작하려면 Google Cloud 프로젝트를 만들거나 선택한 뒤 developerknowledge.googleapis.com를 활성화하고, Developer Knowledge API로 제한한 API 키를 생성한다. 제한하지 않은 키를 에이전트 프롬프트, 저장소, 클라이언트 측 번들, 디버그 로그에 넣어서는 안 된다.
서비스를 활성화하는 최소 명령은 다음과 같다.
gcloud services enable developerknowledge.googleapis.com \
--project="$PROJECT_ID"관리형 애플리케이션에서는 대체로 ADC가 더 깔끔한 경계가 된다. Google의 Python 클라이언트 레퍼런스는 환경에서 탐색하는 자격 증명과 동기·비동기 클라이언트를 설명한다. 덕분에 애플리케이션이 구성 텍스트에서 키를 파싱하도록 만들지 않고, 배포 환경에서 ID를 제공할 수 있다.
대화형 에이전트에는 OAuth도 잘 맞는다. 공유된 고정 시크릿이 아니라 사용자가 연결을 승인하기 때문이다. 정확한 OAuth 흐름은 MCP 호스트에 따라 달라진다. 클라이언트의 인증 지원 여부는 API 자체와 별도로 확인해야 한다. MCP URL을 받는 클라이언트라고 해서 헤더, 시크릿 변수, 토큰 갱신을 모두 같은 방식으로 처리하는 것은 아니다.
최소한의 문서 조회 워크플로
프로덕션 에이전트라면 문서 조회의 경계를 명확히 드러내야 한다.
- 질문에서 시크릿과 무관한 저장소 내용을 제거한다.
SearchDocumentChunks로 공식 코퍼스를 검색한다.- 상위 문서 리소스 기준으로 결과를 중복 제거한다.
- 작업에 주변 맥락이 필요하다면 가장 관련성 높은 전체 문서를 조회한다.
- 반환된 URI, 제목, 타임스탬프 또는 메타데이터, 선택한 발췌문을 보존한다.
- 보존한 근거만 바탕으로 답하도록 모델에 지시한다.
- 에이전트가 코드나 인프라를 변경하기 전에 테스트와 정책 검사를 실행한다.
검색용 REST 엔드포인트는 Google의 REST 레퍼런스에 문서화되어 있다.
GET https://developerknowledge.googleapis.com/v1/documents:searchDocumentChunks간단한 API 키 요청은 다음과 같은 형태다.
curl --get \
'https://developerknowledge.googleapis.com/v1/documents:searchDocumentChunks' \
--data-urlencode 'query=Cloud Storage bucket retention policy' \
--data-urlencode 'pageSize=5' \
--data-urlencode "key=$DEVELOPERKNOWLEDGE_API_KEY"파서를 고정 구현하기 전에는 현재 REST 레퍼런스에서 정확한 응답 스키마와 필드 이름을 확인해야 한다. 검색은 청크와 상위 문서 이름을 반환하며, 문서 조회는 그 이름을 입력으로 사용한다.
빈 결과, 누락된 상위 리소스, 페이지네이션, 인증 실패, 할당량 또는 속도 제한 응답은 모의 응답이나 스냅샷 응답으로 에이전트를 테스트하자. 재시도 로직은 모델 프롬프트 밖에 두고, 제한된 백오프와 근거를 가져오지 못했을 때의 명확한 대체 경로를 마련해야 한다.
직접 API, MCP, 웹 페이지 중 무엇을 쓸까?
같은 문서 소스라도 세 가지 방식으로 노출할 수 있다.
| 상황 | 적합한 경로 | 이유 |
|---|---|---|
| 서비스에 재현 가능한 조회와 인용이 필요함 | REST API 또는 클라이언트 라이브러리 | 애플리케이션이 파싱, 캐싱, 근거 저장을 제어할 수 있음 |
| 코딩 어시스턴트에 필요할 때만 Google 컨텍스트를 제공 | Developer Knowledge MCP 서버 | 별도 접착 코드 없이 에이전트가 검색·조회 도구를 호출할 수 있음 |
| 지원 코퍼스 밖에 있는 페이지 | 직접 페이지 접근 또는 별도 소스 커넥터 | Developer Knowledge 코퍼스에는 없는 소스를 대신 답할 수 없음 |
| 사람이 레이아웃, 탐색, 대화형 예시를 살펴봄 | 브라우저/페이지 접근 | Markdown 조회는 시각적 페이지 검사가 아님 |
Google의 MCP 문서는 엔드포인트를 https://developerknowledge.googleapis.com/mcp로 안내한다. MCP는 에이전트를 위한 어댑터일 뿐, 별도의 지식 베이스가 아니다. 원격 서버 설정의 대표적인 형태는 다음과 같다.
{
"mcpServers": {
"google-developer-knowledge": {
"serverUrl": "https://developerknowledge.googleapis.com/mcp",
"headers": {"x-goog-api-key": "${DEVELOPERKNOWLEDGE_API_KEY}"}
}
}
}호스트가 문서화한 시크릿 변수 문법을 사용해야 하며, 리터럴 ${...} 확장이 어디서나 동작한다고 가정하면 안 된다. 컨텍스트 비용도 계속 고려할 문제다. 모든 작업에 모든 도구를 노출하면 도구 정의와 의사결정 오버헤드가 늘어날 수 있다. 여러 서버를 쓰는 에이전트 구성에 관한 한 실제 사용자 토론에서도 이 우려가 직접 언급됐다.
“MCPs are very context heavy compared to skills - which only take up a few lines of text until they are invoked.” — u/junlim, Reddit 토론
그렇다고 Developer Knowledge MCP 서버를 포기해야 한다는 뜻은 아니다. Google 중심 작업에만 조건부로 제공해야 한다는 의미다. Firebase, Android, Google Cloud, Maps, Flutter를 다루는 에이전트는 이 소스의 도움을 받을 수 있지만, 무관한 스택을 수정하는 에이전트가 기본적으로 호출할 필요는 없다.
Google 개발자 문서에서 API가 스크래핑보다 나은 경우
다음 조건 대부분에 해당한다면 API를 사용하자.
- 작업 대상이 Google 소유 개발자 문서다.
- 에이전트에 일회성 페이지 요청이 아닌 재현 가능한 검색이 필요하다.
- 답변에 인용이나 보존 가능한 출처 이력이 필요하다.
- 에이전트가 관련 청크와 완전한 문서를 구분해야 한다.
- 워크플로에 구조화된 페이지네이션, 일괄 처리, 캐싱이 필요하다.
- 페이지 디자인이 바뀌어도 HTML 파서를 새로 만들고 싶지 않다.
물론 스크래핑이 적절한 대안일 때도 있다. 필요한 페이지가 지원 코퍼스에 없거나, 시각적 상호작용이 작업의 일부이거나, 정확한 렌더링 HTML과 탐색 상태가 중요할 때다. API 접근이 불가능한 장애 상황에서 임시 확인 수단으로도 쓸 수 있다. 다만 그 방식이 모르는 사이 프로덕션 조회 계약으로 굳어져서는 안 된다.
| 판단 요소 | Developer Knowledge API | 개발자 페이지 스크래핑 |
|---|---|---|
| 탐색 | 인덱싱된 코퍼스 내 서비스 검색 | 검색 기능을 구축하거나 알려진 URL에서 시작 |
| 출력 | 청크, 문서 리소스, Markdown | HTML 또는 렌더링된 페이지 콘텐츠 |
| 인용 워크플로 | 상위 리소스와 문서 URI가 명시적 | 애플리케이션이 링크를 추출하고 보존해야 함 |
| 레이아웃 유지보수 | API 계약이 경계가 됨 | 디자인 변경 후 선택자가 깨질 수 있음 |
| 범위 | 지원되는 공개 개발자 코퍼스 | 접근 및 robots 규칙을 따르는 모든 공개 페이지 |
| 시각적 충실도 | 목표가 아님 | 브라우저 자동화를 쓰면 렌더링 레이아웃 보존 가능 |
| 에이전트 제어 흐름 | 검색, 조회, 종합 | 대개 가져오기, 파싱, 정제, 추론 순서 |
API가 새로 게시된 모든 페이지를 즉시 제공한다고 보장하지는 않는다. Google의 릴리스 노트에는 인덱싱 업데이트가 설명되어 있지만, 에이전트는 최신성을 이미 최신 페이지가 인덱싱됐다는 증거가 아니라 확인해야 할 속성으로 취급해야 한다. 출시 당일 마이그레이션이라면 반환된 메타데이터를 현재 공식 페이지와 비교하고, 근거가 없으면 안전하게 실패 처리해야 한다.
실제로 배포할 에이전트 정책
Google 전용 코딩 에이전트라면 다음 라우팅 규칙을 적용할 수 있다.
- 정확한 구현 세부 사항: 먼저
SearchDocumentChunks를 호출하고, 청크에 사전 요구 사항이 없다면 상위 문서를 가져온다. - 여러 페이지에 걸친 설계 질문: 검색 후 관련된 소수의 상위 리소스에
BatchGetDocuments를 사용한다. - 단순 설명 질문:
AnswerQuery를 사용하되, 응답에 참조 자료를 반드시 포함하게 한다. - Google 외부 또는 비공개 문서: 승인된 다른 커넥터로 라우팅한다.
- 코드 또는 인프라 쓰기: 문서 조회는 참고용일 뿐이며 테스트, IAM, 검토, 배포 통제는 계속 필수다.
정책이 허용하는 범위에서 완전한 문서를 캐시하고, 반복 검색은 디바운싱하며, 원본 시크릿이나 불필요한 저장소 컨텍스트 대신 소스 URI를 기록하자. 가져온 Markdown도 신뢰할 수 없는 입력으로 다뤄야 한다. 출처가 권위 있다고 해서 쓰기 권한 도구를 가진 에이전트에 포함된 모든 지시가 안전해지는 것은 아니다.
남는 선택지는 단순하다. API는 HTML 스크래핑보다 깔끔하고 감사하기 쉬운 계약을 에이전트에 제공하지만, 브라우저가 주는 범위와 즉각적인 페이지 충실도는 포기한다. 지원되는 Google 문서에서는 API를 기본값으로 선택하고, 스크래핑이나 다른 커넥터는 두 경로를 보이지 않게 섞지 말고 명시적인 대체 수단으로 유지하는 편이 좋다.
Google Developer Knowledge API FAQ
Developer Knowledge API는 Google Search와 같은 서비스인가요?
아니다. 일반 웹 검색 API가 아니라 지원되는 Google 개발자 코퍼스를 대상으로 하는 문서 조회 서비스다. 비공개 문서, 임의의 GitHub 콘텐츠, Google 관련 모든 페이지를 자동으로 검색하지는 않는다.
AnswerQuery와 SearchDocumentChunks 중 무엇을 사용해야 하나요?
범위가 정해진 근거 기반 설명에는 AnswerQuery를 사용한다. 에이전트가 검토 가능한 근거, 정확한 문법, 출처 이력을 필요로 한다면 SearchDocumentChunks를 사용하고, 청크만으로 부족할 경우 상위 문서를 조회한다.
API 키가 반드시 필요한가요?
제한된 API 키는 프로토타입을 만드는 가장 빠른 경로다. 백엔드 클라이언트는 ADC를 사용할 수 있고, 대화형 MCP 통합은 호스트가 지원할 경우 OAuth를 사용할 수 있다. 한 클라이언트가 지원하는 인증 방식이 다른 클라이언트에서도 자동으로 지원된다고 가정해서는 안 된다.
에이전트가 이 API로 Google Cloud 리소스를 배포할 수 있나요?
아니다. 이 API는 문서 컨텍스트를 제공한다. 배포에는 별도의 도구, 자격 증명, IAM 권한, 승인, 검증이 필요하다.
언제 스크래핑을 사용해야 하나요?
페이지가 API 코퍼스 밖에 있거나, 시각적 레이아웃이 중요하거나, 인덱스에 아직 나타나지 않은 페이지가 필요하다면 스크래핑 또는 브라우저 커넥터를 사용한다. 에이전트가 스크래핑 콘텐츠를 API 기반 인용처럼 제시하지 않도록 이 대체 경로를 명시적으로 기록해야 한다.
검색하면 전체 페이지가 반환되나요?
아니다. 검색은 문서 청크를 반환한다. 전체 Markdown 페이지가 필요하다면 반환된 상위 문서 리소스를 GetDocument 또는 BatchGetDocuments와 함께 사용한다.