Agent Registry와 ADK 연동법: 에이전트 엔드포인트와 MCP 도구를 운영하는 기준

Google Cloud 문서 기준 Agent Registry는 에이전트를 프로그램적으로 관리하는 계층이고, ADK는 orchestration agent를 만들고 평가하고 배포하는 프레임워크입니다. 최근 문서에서는 Agent Registry API를 다룰 때 일반 Google Cloud client libraries를 쓸 수 있고, orchestration agent를 만들 때는 ADK를 쓰는 흐름을 권장합니다. 특히 ADK는 Registry의 connection detail을 resolve하고, agent skill과 MCP tool을 가져와 쓸 수 있는 추상화를 제공합니다.

이 구조가 중요한 이유는 간단합니다. 에이전트가 많아질수록 문제는 “프롬프트를 어떻게 쓰느냐”가 아니라 “어떤 에이전트가 어디에 있고, 어떤 권한과 도구를 갖는지 어떻게 관리하느냐”로 바뀝니다.

왜 Agent Registry가 필요한가

초기에는 에이전트 endpoint를 환경변수에 넣어도 됩니다. CUSTOMER_SUPPORT_AGENT_URL, REPORT_AGENT_URL처럼 관리하면 충분해 보입니다. 하지만 팀이 커지면 곧 문제가 생깁니다. staging과 production endpoint가 섞이고, 오래된 agent가 계속 호출되고, 어떤 agent가 어떤 MCP tool을 쓰는지 추적하기 어렵습니다.

Agent Registry는 이 문제를 카탈로그 관점으로 다룹니다. 에이전트를 이름, 버전, endpoint, skill, 권한, 배포 환경 단위로 찾을 수 있어야 합니다. 사람이 README를 읽고 endpoint를 복사하는 방식은 production orchestration에 맞지 않습니다.

ADK는 언제 쓰고 client library는 언제 쓰나

문서의 구분은 실무적으로도 맞습니다. Registry resource를 생성, 조회, 수정, 삭제하는 관리성 작업은 Google Cloud client libraries가 적합합니다. 인증, retry, pagination을 표준 방식으로 처리할 수 있기 때문입니다.

반면 orchestration agent 내부에서 “지금 필요한 agent endpoint를 찾아 호출한다”, “등록된 MCP tool을 가져온다”, “agent skill을 보고 delegation한다” 같은 작업은 ADK가 적합합니다. ADK는 build, run, evaluate, scale 흐름까지 포함합니다. 단순 API client가 아니라 agent runtime 쪽에 더 가깝습니다.

버전 기준을 먼저 정해야 한다

Agent Registry 문서에는 ADK 사용 시 google-adk[a2a]를 설치하고, 최소 google-adk>=1.29.0로 업그레이드해야 한다는 안내가 있습니다. 이 숫자는 운영에서 중요합니다. 에이전트 통신과 discovery는 버전 차이에 민감합니다. 개발자 노트북에는 최신 버전이 깔려 있고, CI 또는 Cloud Run 이미지에는 오래된 버전이 남아 있으면 재현하기 어려운 문제가 생깁니다.

따라서 에이전트 프로젝트에는 다음을 고정해야 합니다.

pip install --upgrade "google-adk[a2a]"

그리고 lockfile 또는 container image tag로 실제 배포 버전을 고정해야 합니다.

에이전트 카탈로그 설계

Registry에 올릴 때 이름만 정하면 부족합니다. 최소한 다음 메타데이터가 필요합니다.

• agent_name: 사람이 읽을 수 있는 이름
• capability: 요약, 코드 리뷰, 리포트 생성, 티켓 분류 등
• environment: dev, staging, production
• owner_team: 장애 시 연락할 팀
• input_schema_version
• output_schema_version
• allowed_tools 또는 MCP tool 목록
• data_classification: public, internal, confidential
• cost_tier: cheap, standard, expensive

이 정도가 있어야 orchestrator가 무작정 호출하지 않고, 작업 요구사항에 맞는 agent를 고를 수 있습니다.

MCP 도구는 권한 경계로 봐야 한다

MCP tool은 에이전트의 손과 발입니다. 문서 검색만 가능한 tool과 결제 취소 API를 호출할 수 있는 tool은 위험도가 다릅니다. Registry에서 MCP tool을 discover할 수 있다는 것은 편리하지만, 동시에 권한 관리가 중요해졌다는 뜻입니다.

운영 기준은 단순해야 합니다. 읽기 전용 tool과 쓰기 tool을 분리합니다. 외부 시스템에 쓰는 tool은 승인 흐름을 둡니다. 개인 정보가 들어가는 tool은 호출 로그와 retention 정책을 정합니다.

평가를 배포 파이프라인에 넣기

ADK는 built-in 및 partner evaluation tools를 통해 execution trajectory를 테스트할 수 있다고 설명합니다. agent는 함수 하나와 다르게 “어떤 길로 답에 도달했는지”가 중요합니다. 최종 답이 맞아도, 중간에 금지된 tool을 호출했거나 필요 없는 외부 API를 여러 번 때렸다면 production 품질이 아닙니다.

배포 전에는 최소한 다음 테스트를 돌려야 합니다.

• 정상 입력 20개에 대한 성공률
• 애매한 입력 20개에 대한 거절 또는 clarification 품질
• tool failure 시 복구 경로
• 권한 없는 tool 요청 차단
• output schema 준수율
• 평균 비용과 p95 latency

실행 체크리스트

• endpoint를 환경변수로 흩뿌리지 않고 Registry로 관리하는가?
• ADK 버전을 google-adk>=1.29.0 이상으로 고정했는가?
• agent별 owner, environment, schema version을 기록했는가?
• MCP tool을 읽기/쓰기/민감 권한으로 분리했는가?
• orchestrator가 capability와 data classification을 보고 agent를 선택하는가?
• 배포 전에 execution trajectory 평가를 수행하는가?
• 오래된 agent version을 호출하지 않도록 deprecation 정책이 있는가?

Agent Registry와 ADK의 조합은 에이전트를 “스크립트 모음”에서 “운영 가능한 서비스 카탈로그”로 옮기는 장치입니다. 에이전트 수가 3개를 넘기 시작했다면, 프롬프트보다 등록, 권한, 평가 기준을 먼저 정리하는 편이 장기적으로 덜 고생합니다.