Google Developer Knowledge API 적용법: 코딩 에이전트의 오래된 문서 문제를 줄이는 설계

Google이 Developer Knowledge API와 공식 MCP Server를 public preview로 공개했다. Google Cloud, Firebase, Android 등 Google 개발 문서를 AI 에이전트와 개발 도구가 구조적으로 검색하고 가져올 수 있게 하는 API다. 기존처럼 웹페이지를 긁거나 모델의 학습 시점 지식에 기대는 방식이 아니라, 공식 문서에서 Markdown 형식의 최신 정보를 검색·조회·질의응답으로 가져오는 구조다.

이 글의 목표는 “새 API가 나왔다”는 소개가 아니라, 실무 프로젝트에서 어디에 붙이면 효과가 있는지 정리하는 것이다. 특히 Google Cloud나 Firebase를 쓰는 팀은 코딩 에이전트가 오래된 SDK 사용법, 폐기된 CLI 옵션, 틀린 IAM 권한을 제안하는 문제를 자주 겪는다. Developer Knowledge API는 이 문제를 줄이는 검색 계층으로 쓸 수 있다.

어떤 문제를 해결하나

코딩 에이전트가 틀리는 대표적인 이유는 문서 최신성이 낮기 때문이다. 모델은 학습 시점 이후의 변경을 모르고, 검색 기능이 있어도 일반 웹 검색 결과가 공식 문서보다 블로그나 오래된 Stack Overflow 답변을 먼저 가져올 수 있다. 클라우드 제품은 릴리스 속도가 빠르기 때문에 이 차이가 실제 장애로 이어진다.

예를 들어 Firebase 보안 규칙, Cloud Run 배포 옵션, BigQuery 권한, Android Gradle 설정은 작은 옵션 변경만으로도 명령이 실패한다. 에이전트가 “그럴듯한” 답을 만들면 개발자는 명령을 실행해 보고 나서야 틀렸다는 걸 안다. 이 과정이 반복되면 AI 도구에 대한 신뢰가 떨어진다.

Developer Knowledge API는 Google 공식 문서에 대한 semantic search, keyword search, document chunk 검색, 문서 조회, grounded Q&A를 제공한다. 에이전트가 답하기 전에 공식 문서 조각을 먼저 찾고, 필요한 경우 전체 Markdown 문서를 가져와 근거로 쓰게 만들 수 있다. 즉 생성 모델 앞에 “공식 문서 검색 레이어”를 두는 방식이다.

기본 구성 요소

Google 발표에서 제시한 진입점은 네 가지다. 첫째, gcloud CLI다. gcloud developer-knowledge answer-query, documents search-chunks, documents describe 같은 명령으로 터미널에서 바로 문서 검색과 질의응답을 할 수 있다. Cloud Shell에는 기본 제공되고, 일반 Google Cloud SDK 환경에서도 쓸 수 있다고 안내됐다.

둘째, agent skill이다. Google은 AI coding assistant가 Developer Knowledge MCP server 또는 REST API를 사용하도록 안내하는 skill을 제공한다. 발표에는 npx skills add google/skills --skill retrieving-developer-knowledge 명령이 예시로 나온다. Claude Code, Cursor, GitHub Copilot, Google Antigravity 같은 도구와 연결하는 것을 염두에 둔 형태다.

셋째, client libraries다. C#, Go, Java, Node.js/TypeScript, PHP, Python, Ruby용 라이브러리가 제공된다. AnswerQuery, SearchDocumentChunks, GetDocument, BatchGetDocuments 같은 기능을 운영 시스템이나 내부 봇에 직접 넣을 수 있다. BatchGetDocuments는 최대 20개 문서를 한 번에 가져오는 용도로 소개됐다.

넷째, API Explorer다. 코드를 쓰기 전에 요청과 응답 구조를 확인하는 인터랙티브 환경이다. 운영 자동화에 넣기 전, 어떤 쿼리가 어떤 문서 조각을 반환하는지 확인하는 데 적합하다.

에이전트 워크플로우에 넣는 순서

가장 안전한 패턴은 “검색 후 생성”이다. 에이전트가 Google Cloud 관련 질문을 받으면 먼저 searchDocumentChunks로 관련 문서 조각을 찾는다. 조각만으로 충분하면 그 근거를 요약해 답하고, 부족하면 documents.get으로 전체 Markdown 문서를 가져온다. 마지막으로 답변에는 어떤 문서에 근거했는지 남긴다.

두 번째 패턴은 오류 추적이다. 발표 예시처럼 error.txt를 answer-query에 넣어 에러 메시지를 공식 문서 기준으로 해석하게 할 수 있다. 배포 실패, 권한 오류, SDK 마이그레이션 오류처럼 검색 키워드를 사람이 고르기 어려운 상황에서 유용하다. 단, 에러 로그에 토큰이나 개인정보가 포함되지 않게 먼저 마스킹해야 한다.

세 번째 패턴은 CI 보조다. Pull Request에서 Terraform, Firebase rules, Android 설정 파일이 바뀌었을 때 관련 공식 문서를 찾아 “현재 문서 기준으로 옵션이 유효한지” 확인하는 봇을 만들 수 있다. 이때 모델이 임의로 수정 커밋을 만들기보다, 근거 문서와 검토 항목을 댓글로 남기게 하는 편이 안전하다.

token-efficient하게 쓰는 방법

문서 검색 API를 붙였다고 자동으로 비용이 줄지는 않는다. 검색 결과를 너무 많이 넣으면 모델 입력이 커지고, 오히려 비용과 지연시간이 늘어난다. Google이 agent skill에서 제안하는 핵심도 먼저 chunk를 검색하고 필요한 문서만 가져오는 다단계 방식이다.

실무에서는 쿼리당 chunk 개수를 제한해야 한다. 처음에는 3~5개 조각만 모델에 넣고, 답변 신뢰도가 낮거나 서로 충돌하는 내용이 있을 때만 전체 문서를 가져오게 한다. 문서 제목, URL, 업데이트 날짜, 제품명, API 버전을 함께 저장하면 같은 질문을 반복할 때 캐시를 적용하기 쉽다.

또한 프로젝트 컨텍스트와 문서 컨텍스트를 섞지 말아야 한다. 프로젝트의 실제 설정값, 리전, 서비스 계정, IAM 정책은 내부 데이터다. Google 공식 문서는 외부 근거다. 모델 프롬프트에서 이 둘을 구분해 “공식 문서는 근거, 프로젝트 파일은 적용 대상”으로 명시해야 잘못된 일반화가 줄어든다.

보안과 운영상 주의점

문서 검색 자체는 읽기 작업이지만, 에이전트가 그 결과를 바탕으로 명령을 실행하면 쓰기 작업으로 바뀐다. 예를 들어 Cloud Run 배포 옵션을 찾은 뒤 실제 배포 명령을 실행하는 단계는 별도 승인 경계가 필요하다. Developer Knowledge API는 정답 근거를 줄 뿐, 운영 환경 변경의 책임을 대신 지지 않는다.

인증 방식도 확인해야 한다. 발표는 Application Default Credentials와 API key 사용을 언급한다. 내부 도구라면 가능하면 서비스 계정과 최소 권한을 쓰고, API key를 저장소에 넣지 않는다. MCP 서버를 IDE에 연결할 때도 개인 계정 권한이 과도하게 넓지 않은지 봐야 한다.

로그 정책도 필요하다. 개발자가 던진 질문, 에러 메시지, 검색 결과, 모델 답변이 어디에 남는지 확인해야 한다. 특히 에러 로그를 그대로 보내는 워크플로우는 secret masking을 기본 단계로 넣어야 한다. 문서 검색 도구가 안전해도 입력 데이터가 민감하면 문제가 된다.

실행 체크리스트

• Google Cloud, Firebase, Android 관련 질문만 Developer Knowledge API로 라우팅한다.
• 에이전트가 답하기 전에 searchDocumentChunks를 먼저 호출하도록 규칙을 만든다.
• chunk 3~5개로 시작하고, 부족할 때만 전체 문서를 가져온다.
• 답변에는 문서 제목과 근거 요약을 남기게 한다.
• 에러 로그를 질의에 넣기 전 secret과 개인정보를 마스킹한다.
• CI 봇은 자동 수정보다 근거 문서와 검토 항목 댓글부터 시작한다.
• MCP 서버 인증은 최소 권한 계정으로 구성하고 API key를 저장소에 넣지 않는다.
• 한 달 뒤 “문서 오류로 인한 재시도 횟수”와 “에이전트 답변 수정률”을 비교해 효과를 측정한다.