클라우드 런 AI 에이전트 배포법: ADK·MCP 서버 연동 단계별 가이드

핵심 메시지

• 클라우드 런은 요청이 올 때만 컨테이너를 깨우고 트래픽이 없으면 0으로 축소돼, 유휴 시간에는 비용이 들지 않아 AI 에이전트 호스팅에 잘 맞는다.
• ADK(Agent Development Kit)로 에이전트를 작성하고, 여기에 MCP 서버와 위키피디아 조회 도구를 연결해 '도구를 쓰는' 에이전트를 구성한다.
• 배포에서 가장 흔히 놓치는 부분은 서비스 계정 권한으로, run.invoker와 Vertex AI 사용자 역할을 부여하지 않으면 403이나 런타임 권한 오류가 난다.
• ADK가 제공하는 배포 명령 하나가 소스에서 컨테이너를 빌드해 Artifact Registry에 올리고 클라우드 런 서비스까지 만들어 준다.
• 도구를 MCP로 붙였기 때문에 접착 코드를 다시 쓰지 않고도 에이전트 기능을 계속 확장할 수 있다.

쉽게 이해하기

영상은 노트북에서만 돌던 AI 에이전트를 구글 클라우드 런에 올려 인터넷에 공개하는 전 과정을 다룬다. 클라우드 런을 '팝업 상점'에 비유하는데, 요청이 들어오면 컨테이너가 열려 앱을 실행하고 트래픽이 몰리면 자동으로 복제본을 늘리며, 아무도 찾지 않을 때는 0으로 축소돼 유휴 비용이 발생하지 않는다. 개발자는 포트를 여는 컨테이너만 준비하면 확장·부하 분산·TLS·로그·신원 관리는 클라우드 런이 알아서 처리한다.

준비물은 구글 클라우드 계정과 프로젝트 ID 두 가지다. 클라우드 셸에서 프로젝트를 선택하고 배포에 필요한 API(Run, Cloud Build, Artifact Registry, Vertex AI 등)를 한 번 활성화한 뒤, 작업 폴더와 requirements.txt를 만든다. 이때 의존성은 최소한으로 유지하고 버전을 고정해 컨테이너를 가볍게, 콜드 스타트를 짧게 유지하는 것이 권장된다. 모델 선택과 MCP 서버 URL 같은 설정은 .env 파일로 코드와 분리한다.

에이전트는 'Zoo Tour Guide(동물원 안내)'라는 예제로 만든다. 사용자의 첫 질문을 공유 상태에 저장하는 작은 도구, 보안 MCP 서버에 연결되는 도구 세트, 그리고 랭체인 어댑터로 감싼 위키피디아 조회 도구를 갖춘다. 실제 동작은 두 전문 에이전트로 나뉜다. 리서처 에이전트는 상태에서 질문을 읽어 MCP 서버와 위키피디아 중 무엇을(또는 둘 다) 쓸지 고르고, 프리젠터 에이전트는 그 결과를 받아 동원 정보부터 일반 상식까지 친근한 답변으로 정리한다. 둘은 순차 워크플로 에이전트로 묶여 상태를 넘겨 가며 실행되며, 대화의 진입점인 루트 에이전트가 인사와 상태 저장을 담당한다.

권한 설정은 배포의 핵심이다. 서비스 계정에 MCP 서버를 호출할 run.invoker 역할을 바인딩하지 않으면 403 오류가 잦고, Vertex AI 사용자 역할이 없으면 서비스는 뜨지만 모델 호출이 런타임에 실패한다. 보호된 MCP 서버에는 서명된 ID 토큰을 받아 매 호출에 베어러 토큰으로 전달한다.

마지막으로 ADK 배포 명령을 실행하면 소스에서 컨테이너가 빌드돼 레지스트리에 올라가고 클라우드 런 서비스가 생성된다. UI 플래그를 주면 빠른 테스트용 ADK 웹 UI가 함께 뜬다. 명령이 끝나면 공개 URL이 출력되고, 브라우저에서 토큰 스트리밍을 켠 채 질문을 던지면 리서처가 MCP 서버와 위키피디아를 호출하는 과정을 실시간으로 볼 수 있다. 테스트가 끝나면 서비스와 빌드 저장소를 삭제해 자원을 정리한다.

주요 인사이트

• 클라우드 런의 '0으로 축소' 특성 덕분에 평소엔 잠들어 있다가 요청이 올 때만 깨어나는 에이전트를 저비용으로 운영할 수 있다.
• 인사(루트 에이전트)와 실제 작업(워크플로)을 분리하면 로그에서 흐름을 따라가기 쉬워 디버깅이 편해진다.
• 의존성 버전을 고정하는 사소해 보이는 습관이 라이브러리 업데이트로 인한 예기치 못한 파손을 막아 준다.
• MCP 서버 호출 권한(run.invoker)을 잊는 것이 실전에서 403 오류의 흔한 원인이며, 서비스 계정에는 최소 권한만 부여하는 것이 안전하다.
• 순차 워크플로로 시작해도, 이후 루프 에이전트나 병렬 에이전트 같은 더 복잡한 패턴으로 확장할 여지를 남길 수 있다.

자주 묻는 질문

관련 AI 소식