Google ADK는 AI 에이전트를 구축, 평가 및 배포하기 위한 오픈 소스 프레임워크이며, Agentspace와 같은 Google 제품 내 실제 에이전트를 지원합니다. OpenAI Agents SDK와 같은 다른 에이전트 스택을 이미 살펴보셨다면, ADK는 Gemini 및 Vertex AI와 밀접하게 연동하면서 동일한 영역을 다룹니다. 이 가이드는 ADK가 무엇인지, 핵심 요소들이 어떻게 결합되는지, 그리고 Apidog와 같은 도구가 에이전트가 호출하는 API를 테스트하는 데 어떻게 도움이 되는지 설명합니다.
Google ADK란 무엇인가
ADK는 Agent Development Kit의 약자입니다. Google은 2025년 4월 Google Cloud Next에서 에이전트 정의, 도구 제공, 여러 에이전트 구성, 동작 평가, 프로덕션 배포 등 전체 에이전트 수명 주기를 위한 오픈 소스 툴킷으로 ADK를 소개했습니다.
Python으로 시작했으며, Google은 이후 Java를 추가했고, Go 및 TypeScript 지원도 뒤따랐습니다. 이 프레임워크는 Google이 Agentspace 및 고객 참여 스위트(Customer Engagement Suite)에서 에이전트를 위해 내부적으로 사용하는 것과 동일한 것이므로, 장난감 SDK가 아닙니다. 프로덕션 워크로드를 위해 구축되었습니다.
ADK는 모델에 구애받지 않지만 Google에 최적화되어 있습니다. Gemini 및 Vertex AI Model Garden을 통해 사용할 수 있는 모든 모델과 가장 잘 작동하며, LiteLLM에 연결하여 Anthropic, Meta, Mistral 및 기타 제공업체에 에이전트를 연결할 수 있습니다. 단일 모델에 얽매이지 않고 긴밀한 Gemini 통합을 얻을 수 있습니다.
Gemini 및 Vertex AI 생태계에서 ADK의 위치
세 가지 레이어를 분리하는 것이 도움이 됩니다:
- 모델. Gemini (또는 Vertex AI Model Garden 또는 LiteLLM을 통한 다른 제공업체)가 추론을 수행합니다.
- 프레임워크. ADK는 에이전트를 정의하고, 도구를 연결하고, 다중 에이전트 흐름을 오케스트레이션하는 코드 레이어입니다.
- 런타임. Vertex AI Agent Engine은 프로덕션에서 에이전트가 실행되는 관리형의 확장 가능한 호스트입니다. Cloud Run 또는 모든 컨테이너 런타임에 배포할 수도 있습니다.
따라서 ADK는 개발자 지향적인 레이어입니다. Gemini는 그 아래에서 인텔리전스를 제공하고, Vertex AI Agent Engine은 그 위에서 관리형 홈을 제공합니다. 이 세 가지를 함께 사용하거나, ADK를 로컬에서 실행하고 다른 곳에 배포할 수도 있습니다. 어떤 것도 단일 경로를 강요하지 않습니다.
핵심 개념
몇 가지 구성 요소가 작성할 대부분의 내용을 다룹니다.
에이전트
기본 단위는 LLM 기반 에이전트입니다. Python에서는 google.adk.agents에서 이를 가져옵니다. 클래스는 LlmAgent이며, Agent는 이를 위한 편리한 별칭입니다. 모델, 이름, 동작을 형성하는 지시사항, 그리고 도구 목록을 제공합니다.
from google.adk.agents import Agent
def get_exchange_rate(base: str, target: str) -> dict:
"""Return the exchange rate between two currencies."""
# call your real FX API here
return {"base": base, "target": target, "rate": 1.08}
currency_agent = Agent(
name="currency_exchange_agent",
model="gemini-2.0-flash",
instruction="You help users convert between currencies. Stick to the facts.",
tools=[get_exchange_rate],
)
이것은 작동하는 단일 에이전트입니다. 지시사항은 무엇을 해야 하는지 알려주고, 도구 목록은 무엇을 호출할 수 있는지 알려줍니다.
도구
도구는 에이전트가 텍스트 생성 이상의 작업을 수행하는 방법입니다. ADK에서는 일반 Python 함수가 도구입니다. 함수의 이름, 타입 힌트, 독스트링(docstring)은 모델에게 언제 어떻게 호출해야 하는지 알려주므로, 명확한 독스트링이 예상보다 중요합니다.
자체 함수 외에도 ADK는 google_search 및 코드 실행과 같은 내장 도구를 제공하며, 외부 도구 서버 연결을 위한 Model Context Protocol (MCP)을 지원합니다. 또한 LangChain 또는 LlamaIndex와 같은 타사 라이브러리를 래핑하거나 다른 에이전트를 도구로 사용할 수 있습니다. 대부분의 에이전트는 이러한 도구를 통해 외부 REST API를 호출하게 되는데, 이는 나중에 테스트 및 목(mock)이 필요한 정확한 지점입니다.
다중 에이전트 시스템
단일 에이전트도 많은 것을 할 수 있지만, ADK는 계층 구조를 위해 구축되었습니다. 특화된 에이전트들을 더 큰 시스템으로 구성하고 코디네이터가 그들 사이에서 작업을 라우팅하도록 합니다.
프레임워크는 결정적 제어를 위한 워크플로 에이전트를 제공합니다: SequentialAgent는 서브 에이전트를 순서대로 실행하고, ParallelAgent는 동시에 실행하며, LoopAgent는 조건이 충족될 때까지 반복합니다. 이것들을 LLM 기반 라우팅과 혼합하면 여러 서브 에이전트로 작업을 분산하고 그 결과를 병합하는 연구 에이전트를 구축할 수 있습니다.
러너
프로덕션 환경에서는 에이전트를 직접 호출하지 않습니다. Runner는 ADK의 실행 엔진입니다. 세션을 관리하고, 이벤트 흐름을 구동하며, 상태를 업데이트하고, 모델을 호출하며, 도구 호출을 조정합니다. 개발 중에는 CLI를 사용하여 상용구를 건너뛸 수 있습니다: adk run은 대화형 터미널 세션을 시작하고, adk web은 에이전트와 채팅하고 각 단계를 검사하기 위한 로컬 브라우저 UI를 엽니다.
평가 및 배포
ADK는 평가 하네스를 포함하고 있어, 단순히 출력을 눈으로 확인하는 것이 아니라 예상되는 궤적과 응답에 대해 에이전트의 점수를 매길 수 있습니다. 프롬프트, 도구 또는 모델을 변경함에 따라 에이전트 동작이 달라지기 때문에 이는 중요합니다.
배포의 경우, 관리형 경로와 휴대용 경로가 있습니다. Vertex AI Agent Engine은 인프라가 자동으로 처리되는 완전 관리형의 확장 가능한 런타임을 제공합니다. 더 휴대성을 원한다면, 에이전트를 컨테이너로 패키징하여 Cloud Run 또는 모든 컨테이너 플랫폼에 배포할 수 있습니다.
고수준 예시
다음은 작은 다중 에이전트 설정의 형태입니다. 코디네이터가 두 명의 전문가에게 위임합니다.
from google.adk.agents import Agent
flights = Agent(
name="flight_agent",
model="gemini-2.0-flash",
instruction="Find flight options for the user's route and dates.",
tools=[search_flights], # your function wrapping a flights API
)
hotels = Agent(
name="hotel_agent",
model="gemini-2.0-flash",
instruction="Find hotel options near the destination.",
tools=[search_hotels], # your function wrapping a hotels API
)
trip_planner = Agent(
name="trip_planner",
model="gemini-2.0-flash",
instruction="Plan a trip. Delegate flight and hotel lookups to your sub-agents.",
sub_agents=[flights, hotels],
)
코디네이터는 요청에 대해 추론하고 적절한 서브 에이전트에게 전달합니다. 각 서브 에이전트는 도구 함수를 통해 실제 API를 호출합니다. 전체를 Runner를 통해 실행하거나 adk web을 통해 상호 작용하며 테스트할 수 있습니다.
ADK 대 OpenAI Agents SDK
둘 다 도구, 핸드오프, 추적 기능을 갖춘 코드 우선 에이전트 프레임워크입니다. 차이점은 생태계의 인력(gravity)입니다.
| Google ADK | OpenAI Agents SDK | |
|---|---|---|
| 기본 모델 | Gemini (Vertex AI) | OpenAI 모델 |
| 기타 모델 | Vertex AI Model Garden, LiteLLM | LiteLLM 및 기타 |
| 언어 | Python, Java, Go, TypeScript | Python, JavaScript/TypeScript |
| 다중 에이전트 | 서브 에이전트 + 순차, 병렬, 루프 워크플로 에이전트 | 도구로서의 에이전트 및 핸드오프 |
| 관리형 런타임 | Vertex AI Agent Engine | 직접 구성 |
| 도구 프로토콜 | MCP, 내장 도구, 함수 도구 | MCP, 함수 도구 |
스택이 이미 Google Cloud에 있다면 ADK와 Vertex AI가 자연스러운 조합입니다. OpenAI 우선이라면 OpenAI Agents SDK를 사용하면 됩니다. 둘 다 MCP를 지원하므로 도구 서버를 공유할 수 있습니다.
ADK를 사용해야 하는 경우
다음과 같은 경우 ADK를 고려하십시오:
- Google Cloud를 기반으로 구축하고 Gemini와 Vertex AI Agent Engine의 관리형 런타임을 원할 때.
- 명시적인 순차, 병렬 또는 루프 제어를 통한 다중 에이전트 오케스트레이션이 필요할 때.
- 나중에 추가하는 것이 아니라 프레임워크에 평가 기능이 내장되어 있기를 원할 때.
- 모델을 교체할 것으로 예상하고 LiteLLM 및 Vertex AI Model Garden을 비상 수단으로 활용하고 싶을 때.
다른 모델 생태계에 확고하게 자리 잡았거나, 한두 개의 함수 호출이 있는 단일 프롬프트로 전체 사용 사례를 처리할 수 있다면 ADK를 건너뛸 수 있습니다. 에이전트 프레임워크는 구조를 추가하며, 작업이 작을 때는 구조에 비용이 따릅니다.
Apidog의 역할: 에이전트가 호출하는 API 테스트 및 목업
ADK는 에이전트를 오케스트레이션합니다. 에이전트가 의존하는 외부 API를 테스트하지 않으며, 이것이 일찍 메워야 할 간극입니다.
에이전트의 모든 의미 있는 도구는 LLM 엔드포인트, 결제 API, 내부 마이크로서비스, 타사 데이터 소스 등 어떤 것을 호출합니다. 이 중 하나가 예상치 못한 형태를 반환하면 에이전트가 잘못된 입력으로 추론하게 되고 오류를 추적하기 어려워집니다. Apidog는 문제가 발생하기 전에 계약을 확정하는 곳입니다. 명확히 말하자면: Apidog는 에이전트 프레임워크가 아니며 ADK를 대체하지 않습니다. 에이전트의 도구가 사용하는 API보다 한 레이어 아래에 위치합니다.
ADK 개발 중 몇 가지 구체적인 사용 사례:
- 도구가 호출하는 엔드포인트를 목업합니다. LLM 또는 도구의 REST 엔드포인트에 대한 목업 API를 설정하여 토큰을 소모하거나 속도 제한에 걸리지 않고 에이전트를 개발하고 실행할 수 있습니다. 에이전트가 처리해야 하는 오류 사례를 포함하여 응답을 제어할 수 있습니다.
- 도구의 응답 형태를 단언(assert)합니다. API 단언을 사용하여 도구 엔드포인트가 에이전트가 예상하는 필드를 정확히 반환하는지 확인할 수 있습니다. 계약이 변경되면 혼란스러운 에이전트 스크립트에서가 아니라 테스트에서 이를 감지합니다.
- 환경별 키를 관리합니다. 개발, 스테이징 및 프로덕션 키를 Apidog 환경에 보관하여 동일한 도구 호출이 모든 단계에서 깨끗하게 실행되도록 합니다.
특히 에이전트를 대상으로 하는 더 깊이 있는 설명을 원하시면, 프로덕션에서 문제가 발생하기 전에 AI 에이전트의 도구 호출을 테스트하는 방법을 참조하십시오. Apidog를 다운로드하고 몇 분 안에 단일 엔드포인트를 목업할 수 있습니다.
자주 묻는 질문
Google ADK는 무료이며 오픈 소스인가요?
네. ADK는 Apache 라이선스 하의 오픈 소스 GitHub 저장소이며, 비용 없이 로컬에서 실행할 수 있습니다. 호출하는 모델과 Vertex AI Agent Engine과 같이 배포하는 모든 관리형 런타임에 대해서는 비용을 지불합니다. 프레임워크 자체는 무료입니다.
ADK는 Gemini에서만 작동하나요?
아니요. ADK는 Gemini 및 Vertex AI에 최적화되어 있지만, 모델에 구애받지 않습니다. Vertex AI Model Garden 및 LiteLLM을 통해 Anthropic, Meta, Mistral 및 기타 제공업체에서 에이전트를 실행할 수 있습니다. Gemini는 기본값이지만 필수 사항은 아닙니다.
ADK는 어떤 언어를 지원하나요?
Python이 가장 먼저 출시되었으며 가장 완벽합니다. Google은 이후 Java를 추가했고, Go 및 TypeScript 지원도 뒤따랐습니다. 오늘날 가장 넓은 기능 범위를 원한다면 Python이 가장 안전한 선택입니다.
ADK 에이전트가 의존하는 API는 어떻게 테스트하나요?
에이전트와 별도로 테스트하십시오. LLM 또는 도구 엔드포인트를 목업하여 에이전트가 실시간 호출 없이 실행되도록 하고, 각 응답이 에이전트가 예상하는 것과 일치하는지 단언하십시오. Apidog는 이 둘 모두를 다루며, ChatGPT API를 테스트하는 방법 가이드는 도구가 호출할 수 있는 LLM 엔드포인트에 대해 동일한 패턴을 보여줍니다.
마무리
Google ADK는 Gemini 및 Vertex AI를 가까이 두고 다른 모델은 설정 변경으로 이용할 수 있는, 에이전트 및 다중 에이전트 시스템을 구축하기 위한 깔끔하고 프로덕션 지향적인 방법을 제공합니다. 하나의 에이전트와 몇 가지 도구로 시작하고, adk web을 활용하여 에이전트의 생각을 관찰한 다음, 작업 요구 사항에 따라 서브 에이전트와 관리형 런타임으로 확장하십시오. 에이전트가 외부 API에 더 많이 의존하게 되면, 해당 API를 목업하고 단언하는 대상으로 취급하십시오. 이것이 Apidog가 처리하는 레이어이며, 불안정한 에이전트 동작이 보통 시작되는 지점입니다.