Google ADK 2.5: 원격 MCP·에이전트→MCP·Cloud Run sandbox로 실행 경계를 다시 잇는 방식

왜 지금 봐야 하나

Google ADK 2.0이 에이전트를 워크플로 그래프의 노드로 바꿨다면, 2.5.0은 그 그래프를 어떻게 바깥 세계와 연결할 것인가에 초점을 맞춘 릴리스다. 2026년 7월 16일 공개된 ADK 2.5.0에서 눈에 띄는 변화는 세 갈래다.

1. ADK 에이전트를 MCP 서버로 바로 내보낼 수 있게 됐다. to_mcp_server를 쓰면 전체 에이전트가 MCP 호스트 입장에서는 단일 도구 하나로 보인다.
2. ManagedAgent가 원격 MCP 서버를 서버 측에서 붙일 수 있게 됐다. ADK 클라이언트가 직접 MCP 세션을 여는 대신, Managed Agents API 백엔드가 서버 측에서 MCP를 호출한다.
3. 코드 실행을 Cloud Run sandbox 안으로 밀어 넣는 선택지가 생겼다. 다만 이것은 "원격 코드 실행 서비스"가 아니라, Cloud Run 컨테이너 안의 로컬 sandbox 바이너리를 호출하는 방식이다.

이 세 변화는 같은 방향을 가리킨다. ADK 2.5는 에이전트 런타임 내부를 더 화려하게 만든 릴리스가 아니라, 프로토콜 경계·실행 경계·보안 경계를 어디에 둘지 다시 설계하게 만드는 릴리스다.

핵심 변화 한눈에 보기

ADK 2.5의 진짜 변화는 "경계의 방향"이다

ADK 2.0에서 중요한 질문은 "에이전트를 워크플로 그래프 안에 어떻게 넣을 것인가"였다. ADK 2.5에서는 질문이 달라진다.

• 우리 에이전트를 다른 호스트가 어떻게 호출할 것인가?
• 우리 에이전트는 외부 MCP 서버를 누구 책임으로 호출할 것인가?
• 코드 실행은 어느 런타임 경계 안에서 허용할 것인가?

이 세 질문은 모두 아키텍처에서 제일 늦게 드러나는 문제들이다. 데모 단계에서는 대충 로컬 함수 호출과 로컬 코드 실행으로 넘어갈 수 있지만, 실제 운영에서는 다음이 먼저 막힌다.

• 에이전트를 IDE·CLI·MCP 호스트에 붙이는 표면이 제각각이다.
• 원격 도구 호출 시 인증 헤더와 비밀키 수명주기를 어디에 둘지 불분명하다.
• 코드 실행을 허용하면 샌드박스 경계가 애매해진다.

ADK 2.5는 이 세 문제에 대해 "그래프는 내부 구조이고, 바깥과 만나는 표면은 별도 프로토콜·서버 측 실행·샌드박스로 분리하자"는 답을 낸다.

to_mcp_server: ADK 에이전트를 "단일 MCP 도구"로 포장한다

to_mcp_server 문서가 분명히 말하는 점이 있다. MCP 호스트는 ADK를 이해할 필요가 없다. 호스트가 보는 것은 MCP 서버 하나와 도구 하나뿐이다.

이 설계의 의미는 생각보다 크다.

1) 하위 에이전트의 내부 도구를 숨기고 계약면을 축소한다

to_mcp_server는 전체 ADK 에이전트와 그 내부 도구 집합을 MCP에서 단일 도구로 노출한다. 호스트는 request 문자열을 보내고, 최종 응답을 받는다. 내부에서 어떤 모델 루프가 돌고 어떤 도구가 선택됐는지는 호스트의 관심사가 아니다.

이건 단순한 래퍼가 아니다. 운영 측면에서는 다음 효과가 있다.

• IDE나 코딩 에이전트에 노출할 도구 개수를 줄일 수 있다.
• 내부 도구 체계가 자주 바뀌어도 바깥 계약은 MCP tool 하나로 고정할 수 있다.
• 내부 에이전트를 팀별·환경별로 교체해도 호스트 쪽 설정 변경을 최소화할 수 있다.

반대로 잃는 것도 있다.

• 호스트 기준으로는 내부 도구별 관측성이 줄어든다.
• 안전장치가 세밀한 함수별 권한이 아니라 "이 에이전트 전체를 도구로 허용할 것인가" 수준으로 올라간다.
• 내부 에이전트가 지나치게 범용이면, 외부에서 보기에는 작은 MCP tool 하나가 사실상 매우 큰 권한을 가지게 된다.

2) 세션은 MCP 연결 단위로 유지된다

to_mcp_server 구현은 MCP connection별로 ADK session 하나를 유지한다. 즉 같은 연결에서 연속 호출하면 단일 멀티턴 대화처럼 이어진다.

이 특징은 두 가지 상황에서 특히 중요하다.

• 로컬 IDE나 CLI가 동일 연결을 재사용할 때: 컨텍스트가 자연스럽게 이어진다.
• 네트워크 MCP 서버를 앞단에 둘 때: 연결 재사용 정책이 세션 지속성과 직결된다.

즉, to_mcp_server는 단순 RPC wrapper가 아니라 연결 수명주기와 대화 수명주기가 연결된 어댑터다. 로드밸런싱이나 프록시를 앞에 둘 경우, 연결 재사용 전략을 설계하지 않으면 기대한 대화 지속성이 깨질 수 있다.

3) transport 선택은 호출자 책임으로 남겨 둔다

문서는 stdio와 streamable-http 중 transport 선택을 호출자에게 남긴다. 이 점도 중요하다. ADK는 "에이전트를 MCP tool로 노출하는 것"만 제공하고, 그 도구를 로컬 프로세스로 띄울지 네트워크 서비스로 띄울지는 배포자가 결정하게 한다.

그래서 to_mcp_server는 프레임워크 기능이면서도 동시에 배포 아키텍처 결정이다.

ManagedAgent + RemoteMcpServer: 원격 MCP를 클라이언트가 아니라 백엔드가 연다

ADK 2.5에서 더 흥미로운 변화는 반대 방향이다. 이번에는 우리 에이전트를 밖으로 내보내는 게 아니라, 바깥의 MCP 서버를 에이전트 쪽으로 끌어오는 문제다.

ManagedAgent 구현과 원격 MCP 샘플이 보여 주는 핵심은 다음과 같다.

1. ManagedAgent는 server-side tools만 지원한다.
2. RemoteMcpServer는 요청 시점에 header_provider로 인증 헤더를 민트해서 백엔드에 전달한다.
3. 실제 MCP 세션은 ADK 클라이언트가 아니라 Managed Agents API 백엔드가 서버 측에서 연다.

이 설계는 로컬 McpToolset과 다르다. 로컬 McpToolset 경로에서는 ADK 애플리케이션 자체가 MCP 세션을 열고 도구를 실행한다. 하지만 ManagedAgent + RemoteMcpServer 경로에서는 ADK가 URL과 헤더만 넘기고, 실행 책임은 서버로 이동한다.

왜 이게 중요한가

에이전트를 프로덕션에 붙일 때 흔한 문제는 "도구를 누가 실행하느냐"보다 "비밀키를 누가 들고 있느냐"다. header_provider가 요청 시점에 동적으로 헤더를 만들고, 백엔드가 원격 MCP 서버에 붙는 구조는 다음 이점을 준다.

• 로컬 개발자 머신이나 thin client에 장기 비밀을 두지 않아도 된다.
• 서버 측 정책에 따라 헤더를 매 턴 새로 발급하거나 회전할 수 있다.
• 브라우저/모바일/경량 클라이언트는 MCP 도구 실행 로직을 몰라도 된다.

반면 대가도 있다.

• 디버깅이 로컬 함수 호출보다 어려워진다. 실패 지점이 ADK 클라이언트, Managed Agents API, 원격 MCP 서버 중 어디인지 분리해야 한다.
• 네트워크 경로와 SSE 스트리밍이 필수가 된다.
• 클라이언트 실행 도구를 섞는 하이브리드 구성이 아니라, 서버 측 실행 가능한 도구 집합으로 모델을 다시 짜야 한다.

single_turn 모드는 왜 강조되는가

ManagedAgent는 mode='single_turn'일 때 부모 LlmAgent의 인라인 도구처럼 동작하도록 설계됐다. 문서와 구현은 이것을 기존 AgentTool 계열 조합의 권장 대체 경로로 둔다.

이 말은 곧, ADK 2.5가 하위 에이전트 합성을 다음처럼 보고 있다는 뜻이다.

• 장기 상태와 복잡한 툴 루프는 ManagedAgent 내부에서 돌린다.
• 부모 에이전트는 그것을 도구 한 번 호출하듯 위임한다.
• 결과는 다시 부모 세션과 이벤트 스트림으로 합쳐진다.

즉, ADK 2.5의 합성 단위는 "모든 도구를 부모가 직접 쥐는 구조"보다 전문화된 하위 에이전트를 경계 하나로 감싸서 위임하는 구조에 더 가깝다.

background + streaming only 제약은 사소하지 않다

ManagedAgent 구현은 interactions 생성 시 background=True를 강제하고, 결과는 열린 스트리밍 연결에서 소비한다고 설명한다. 이것은 단순 구현 세부사항이 아니다.

• 장기 실행 작업과 서버 측 툴 체인을 전제한다.
• polling 기반 단순 request/response로는 충분하지 않다.
• 네트워크나 프록시가 스트리밍 연결을 잘 유지하지 못하면 체감 안정성이 급격히 떨어질 수 있다.

따라서 ManagedAgent는 "API 하나 더 붙였다" 수준이 아니라, 에이전트 상호작용의 시간 모델 자체가 스트리밍 중심이라는 뜻으로 읽어야 한다.

Cloud Run sandbox code executor: 격리 수준은 올라가지만, 세션성은 내려간다

이번 릴리스에서 가장 운영적인 의미가 큰 변화는 Cloud Run sandbox executor다. 다만 이름만 보고 "ADK가 이제 Cloud Run을 원격 코드 실행 서비스처럼 호출한다"고 이해하면 틀린다.

소스가 명시하는 사실은 다르다.

• 이 executor는 Cloud Run 컨테이너 안에서만 쓰도록 설계됐다.
• 외부 머신에서 원격 실행용으로 쓸 수 없다.
• 로컬 guest sandbox 바이너리를 사용해 sandbox do <python_path>로 코드를 실행한다.
• 코드는 stdin으로 전달된다.
• 기본값으로 allow_egress=False다.
• stateful=True와 optimize_data_file=True는 금지된다.

여기서 중요한 것은 Cloud Run sandbox가 "새로운 장기 세션 실행기"가 아니라, 짧은 일회성 코드 실행을 더 안전한 로컬 샌드박스에 넣는 선택지라는 점이다.

왜 stateful을 금지했나

executor 구현은 stateful 설정 자체를 예외로 막는다. 이건 기능이 덜 구현돼서가 아니라, 현재 경계가 one-shot sandbox이기 때문이다.

• 코드가 stdin으로 들어간다.
• 샌드박스 안에서 한 번 실행되고 끝난다.
• 세션 간 파일 상태를 누적하거나 notebook처럼 이어 가는 모델이 아니다.

즉, Cloud Run sandbox executor는 "지속형 작업공간"보다 짧은 검증 코드, 계산, 포맷 변환, 제한된 보조 스크립트 실행에 더 잘 맞는다.

egress가 기본 차단이라는 점을 설계 전제로 봐야 한다

allow_egress=False 기본값은 의도적이다. 운영자는 필요할 때만 네트워크 바깥 호출을 열어야 한다. 이 선택은 코드 실행 기능을 붙일 때 가장 먼저 생기는 질문, 즉 "모델이 만든 코드가 인터넷에 마음대로 나가도 되는가"에 대한 기본 답을 제공한다.

따라서 Cloud Run sandbox executor를 도입할 때는 기능 데모보다 먼저 다음을 정해야 한다.

• 어떤 워크로드에서 egress를 열 것인가
• 열더라도 어떤 대상에만 허용할 것인가
• stdout/stderr와 결과 파일을 어디까지 보존할 것인가
• 시간 제한과 실패 재시도를 어디서 책임질 것인가

이 릴리스가 특히 잘 맞는 팀

ADK 2.5는 모든 사용자에게 동일한 의미를 갖지 않는다. 특히 다음 팀에서 효과가 크다.

1) 여러 호스트에 같은 하위 에이전트를 재사용하려는 팀

내부 조사 에이전트, 사내 문서 에이전트, 배포 점검 에이전트를 이미 ADK로 만들었다면 to_mcp_server는 그것을 Claude Code, Codex, IDE, 사내 MCP 허브에 같은 계약으로 배포하는 길을 연다.

2) 인증 헤더를 클라이언트에 두기 싫은 팀

원격 MCP 서버가 Maps, 내부 API, 검색 시스템처럼 민감한 키를 요구하면 ManagedAgent + RemoteMcpServer 구조가 매력적이다. 헤더 생성과 원격 도구 실행을 서버 쪽으로 옮길 수 있기 때문이다.

3) 코드 실행은 허용하되 런타임 격리를 강하게 잡아야 하는 팀

ADK 기반 코딩 에이전트나 데이터 보조 에이전트를 Cloud Run에 올린다면, Cloud Run sandbox executor는 unsafe local execution보다 훨씬 낫다. 다만 상태 유지형 세션을 기대하면 안 된다.

도입 전에 확인할 체크리스트

to_mcp_server 도입 체크

• 외부 호스트에 노출할 계약을 "도구 여러 개"가 아니라 "에이전트 하나"로 묶는 것이 맞는가
• 같은 MCP 연결을 재사용할 때 세션 지속성이 기대와 일치하는가
• 내부 도구별 관측성이 줄어드는 대신 어떤 로그/trace를 추가로 남길 것인가

ManagedAgent + 원격 MCP 체크

• 도구 실행을 클라이언트가 아니라 백엔드가 맡아야 하는 이유가 분명한가
• header_provider가 턴마다 인증 헤더를 안전하게 갱신할 수 있는가
• 스트리밍 연결이 프록시·게이트웨이·브라우저 환경에서 안정적으로 유지되는가
• 로컬 callable 도구와 섞으려는 설계는 아닌가

Cloud Run sandbox 체크

• 실제 배포 환경이 Cloud Run sandbox 바이너리를 제공하는가
• stateful 세션이 정말 필요 없는가
• egress를 기본 차단 상태로 두고도 워크로드가 동작하는가
• timeout, stdout/stderr 보존, 실패 재시도 기준이 있는가

한 줄 결론

ADK 2.5의 핵심은 모델이 더 똑똑해졌다는 데 있지 않다. 에이전트를 어떤 프로토콜로 노출하고, 외부 도구를 누구 책임으로 호출하며, 코드 실행을 어느 경계 안에 가둘지에 대해 프레임워크가 더 명확한 운영 답을 내기 시작했다는 데 있다.

ADK 2.0이 그래프 런타임을 열었다면, ADK 2.5는 그 그래프를 프로덕션 환경의 실제 경계와 맞물리게 만드는 릴리스다.

References

• Google ADK Python v2.5.0 release notes (2026-07-16): https://github.com/google/adk-python/releases/tag/v2.5.0
• to_mcp_server guide at tag v2.5.0: https://github.com/google/adk-python/blob/v2.5.0/docs/guides/tools/mcp_tool/agent_to_mcp/index.md
• ManagedAgent guide at tag v2.5.0: https://github.com/google/adk-python/blob/v2.5.0/docs/guides/agents/managed_agent/index.md
• Remote MCP sample for ManagedAgent at tag v2.5.0: https://github.com/google/adk-python/blob/v2.5.0/contributing/samples/managed_agent/remote_mcp/README.md
• CloudRunSandboxCodeExecutor source at tag v2.5.0: https://github.com/google/adk-python/blob/v2.5.0/src/google/adk/integrations/cloud_run/_cloud_run_sandbox_code_executor.py
• ADK 2.0 chapter in this series for prior architecture context: ../ai-frontier/14-google-adk-2-0-graph-workflow-runtime.html