Google ADK는 AI 에이전트를 구축, 평가 및 배포하기 위한 오픈 소스 프레임워크입니다. Agentspace와 같은 Google 제품에서 실제 에이전트를 지원하며, OpenAI Agents SDK와 유사하게 에이전트 정의, 도구 연결, 실행, 평가까지 다룹니다. 이 글에서는 ADK의 핵심 구성 요소를 빠르게 정리하고, Apidog로 에이전트가 호출하는 API를 테스트하는 방법까지 구현 관점에서 살펴봅니다.
Google ADK란 무엇인가
ADK는 Agent Development Kit의 약자입니다. Google은 2025년 4월 Google Cloud Next에서 ADK를 공개했으며, 목적은 에이전트의 전체 수명 주기를 코드로 다루는 것입니다.
ADK로 할 수 있는 일은 다음과 같습니다.
- 에이전트 정의
- 도구 연결
- 여러 에이전트 구성
- 에이전트 동작 평가
- 프로덕션 배포
ADK는 Python으로 시작했고, 이후 Java가 추가되었으며 Go 및 TypeScript 지원도 뒤따랐습니다. Google이 Agentspace 및 Customer Engagement Suite에서 사용하는 에이전트 기반과 연결되어 있으므로, 단순한 실험용 SDK가 아니라 프로덕션 워크로드를 염두에 둔 프레임워크입니다.
ADK는 모델에 구애받지 않지만 Google 생태계에 최적화되어 있습니다. Gemini 및 Vertex AI Model Garden의 모델과 잘 맞고, LiteLLM을 통해 Anthropic, Meta, Mistral 등 다른 제공업체의 모델도 연결할 수 있습니다.
Gemini 및 Vertex AI 생태계에서 ADK의 위치
ADK를 이해하려면 세 레이어로 나누어 보는 것이 좋습니다.
- 모델: Gemini, Vertex AI Model Garden 모델, 또는 LiteLLM을 통한 외부 모델이 추론을 수행합니다.
- 프레임워크: ADK가 에이전트 정의, 도구 연결, 다중 에이전트 오케스트레이션을 담당합니다.
- 런타임: Vertex AI Agent Engine은 프로덕션에서 에이전트를 실행하기 위한 관리형 런타임입니다. 필요하면 Cloud Run 또는 다른 컨테이너 런타임에도 배포할 수 있습니다.
즉, ADK는 개발자가 직접 다루는 코드 레이어입니다. Gemini는 지능을 제공하고, Vertex AI Agent Engine은 관리형 실행 환경을 제공합니다. 세 가지를 함께 사용할 수도 있고, ADK를 로컬에서 실행한 뒤 다른 컨테이너 플랫폼에 배포할 수도 있습니다.
핵심 개념
ADK로 구현할 때 가장 자주 사용하는 구성 요소는 다음입니다.
1. 에이전트
ADK의 기본 단위는 LLM 기반 에이전트입니다. Python에서는 google.adk.agents에서 가져옵니다. 클래스 이름은 LlmAgent이고, Agent는 이를 위한 편리한 별칭입니다.
에이전트를 만들 때 주로 지정하는 값은 다음입니다.
-
name: 에이전트 이름 -
model: 사용할 모델 -
instruction: 에이전트의 역할과 행동 규칙 -
tools: 에이전트가 호출할 수 있는 함수 목록 -
sub_agents: 위임 가능한 하위 에이전트 목록
from google.adk.agents import Agent
def get_exchange_rate(base: str, target: str) -> dict:
"""Return the exchange rate between two currencies."""
# 실제 환율 API를 여기에서 호출합니다.
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],
)
이 예제에서 currency_agent는 사용자 요청을 해석하고, 필요하면 get_exchange_rate() 함수를 도구로 호출합니다.
2. 도구
도구는 에이전트가 텍스트 생성 외의 작업을 수행하는 방법입니다. ADK에서는 일반 Python 함수가 도구가 될 수 있습니다.
모델은 다음 정보를 보고 도구 사용 여부를 판단합니다.
- 함수 이름
- 타입 힌트
- 독스트링
- 반환 구조
따라서 도구 함수는 명확하게 작성해야 합니다.
def search_order(order_id: str) -> dict:
"""Find an order by order_id and return its status, items, and total price."""
# 실제 주문 API 호출
return {
"order_id": order_id,
"status": "shipped",
"items": ["keyboard", "mouse"],
"total": 120.0,
}
ADK는 자체 함수 외에도 다음을 지원합니다.
-
google_search같은 내장 도구 - 코드 실행 도구
- Model Context Protocol, MCP
- LangChain 또는 LlamaIndex 같은 외부 라이브러리 래핑
- 다른 에이전트를 도구처럼 사용하는 패턴
실제 프로젝트에서는 대부분의 도구가 내부 REST API, 외부 SaaS API, LLM 엔드포인트 등을 호출합니다. 따라서 도구가 호출하는 API의 응답 형식을 테스트하고 목업하는 과정이 중요합니다.
3. 다중 에이전트 시스템
단일 에이전트로도 많은 작업을 처리할 수 있지만, ADK는 여러 에이전트를 조합하는 구조에 강점이 있습니다.
예를 들어 여행 계획 에이전트를 만든다면 다음처럼 역할을 나눌 수 있습니다.
- 항공권 검색 에이전트
- 호텔 검색 에이전트
- 일정 생성 에이전트
- 최종 응답을 조합하는 코디네이터 에이전트
ADK는 결정적 제어를 위한 워크플로 에이전트도 제공합니다.
-
SequentialAgent: 하위 에이전트를 순서대로 실행 -
ParallelAgent: 하위 에이전트를 동시에 실행 -
LoopAgent: 조건이 충족될 때까지 반복 실행
LLM 기반 라우팅과 이러한 워크플로 에이전트를 함께 사용하면, 작업을 여러 전문 에이전트에 분산하고 결과를 병합하는 구조를 만들 수 있습니다.
4. 러너
프로덕션 코드에서는 에이전트를 직접 호출하기보다 Runner를 사용합니다. Runner는 ADK의 실행 엔진입니다.
Runner가 담당하는 작업은 다음과 같습니다.
- 세션 관리
- 이벤트 흐름 처리
- 상태 업데이트
- 모델 호출
- 도구 호출 조정
개발 중에는 CLI를 사용하면 빠르게 확인할 수 있습니다.
adk run
adk run은 대화형 터미널 세션을 시작합니다.
adk web
adk web은 브라우저에서 에이전트와 대화하고 각 단계를 검사할 수 있는 로컬 UI를 엽니다.
5. 평가 및 배포
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], # 항공권 API를 래핑하는 함수
)
hotels = Agent(
name="hotel_agent",
model="gemini-2.0-flash",
instruction="Find hotel options near the destination.",
tools=[search_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],
)
이 구조에서 trip_planner는 사용자 요청을 해석한 뒤, 항공권이 필요하면 flight_agent에, 숙소가 필요하면 hotel_agent에 위임합니다.
각 하위 에이전트는 도구 함수를 통해 실제 API를 호출합니다. 개발 중에는 adk web으로 실행 흐름을 확인하고, 프로덕션에서는 Runner 또는 관리형 런타임을 통해 실행할 수 있습니다.
ADK 대 OpenAI Agents SDK
둘 다 도구 호출, 핸드오프, 추적 기능을 갖춘 코드 우선 에이전트 프레임워크입니다. 차이는 주로 생태계에 있습니다.
| 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와 Vertex AI를 사용하고 있다면 ADK가 자연스럽습니다. OpenAI 모델과 도구 체인을 중심으로 구축한다면 OpenAI Agents SDK가 더 적합할 수 있습니다. 둘 다 MCP를 지원하므로 동일한 도구 서버를 공유하는 구조도 가능합니다.
ADK를 사용해야 하는 경우
다음 상황이라면 ADK를 고려할 만합니다.
- Google Cloud 기반으로 구축하고 있다.
- Gemini와 Vertex AI Agent Engine을 함께 사용하고 싶다.
- 순차, 병렬, 루프 기반의 명시적 다중 에이전트 제어가 필요하다.
- 평가 기능을 프레임워크 안에서 다루고 싶다.
- 모델 교체 가능성을 열어두고 싶다.
- Vertex AI Model Garden 또는 LiteLLM을 통해 여러 모델을 연결해야 한다.
반대로 다음 상황이라면 ADK가 과할 수 있습니다.
- 단일 프롬프트와 한두 개의 함수 호출로 충분하다.
- 다른 모델 생태계에 이미 강하게 묶여 있다.
- 에이전트 오케스트레이션보다 단순 API 호출 자동화가 목적이다.
에이전트 프레임워크는 구조를 제공합니다. 하지만 작업이 작을 때는 그 구조 자체가 복잡도가 될 수 있습니다.
Apidog의 역할: 에이전트가 호출하는 API 테스트 및 목업
ADK는 에이전트를 오케스트레이션합니다. 하지만 에이전트가 의존하는 외부 API 자체를 테스트하지는 않습니다.
실제 에이전트의 도구는 보통 다음 중 하나를 호출합니다.
- LLM 엔드포인트
- 결제 API
- 내부 마이크로서비스
- 타사 데이터 API
- 검색 API
- 주문, 사용자, 재고 같은 사내 API
이 API 중 하나가 예상과 다른 응답을 반환하면 에이전트는 잘못된 입력을 기반으로 추론합니다. 이 문제는 에이전트 로그만 보고 추적하기 어렵습니다.
여기서 Apidog의 역할은 ADK를 대체하는 것이 아닙니다. Apidog는 에이전트 프레임워크가 아니라, 에이전트 도구가 호출하는 API를 설계, 목업, 테스트하는 레이어입니다.
ADK 개발 중 Apidog를 사용하는 방법
1. 도구가 호출하는 엔드포인트 목업
실제 API가 아직 준비되지 않았거나, 호출 비용과 속도 제한이 부담된다면 목업 API를 먼저 만들 수 있습니다.
예를 들어 에이전트 도구가 다음 API를 호출한다고 가정합니다.
GET /exchange-rate?base=USD&target=KRW
Apidog에서 성공 응답을 다음처럼 정의할 수 있습니다.
{
"base": "USD",
"target": "KRW",
"rate": 1380.25
}
그리고 에러 케이스도 별도로 만들 수 있습니다.
{
"error": "unsupported_currency",
"message": "The target currency is not supported."
}
이렇게 하면 실제 API 없이도 에이전트가 정상 응답과 오류 응답을 모두 처리하는지 테스트할 수 있습니다.
2. 도구 응답 형태 검증
에이전트 도구는 반환 필드에 민감합니다. 예를 들어 에이전트가 rate 필드를 기대하는데 API가 exchangeRate로 바뀌면, 에이전트는 잘못된 응답을 생성할 수 있습니다.
API 단언을 사용하면 응답 계약을 테스트할 수 있습니다.
검증해야 할 항목은 다음과 같습니다.
- 필수 필드 존재 여부
- 필드 타입
- 상태 코드
- 에러 응답 형식
- 배열 또는 객체 구조
- 인증 실패 응답
에이전트 코드에서 문제가 터지기 전에 API 테스트에서 계약 변경을 감지하는 것이 좋습니다.
3. 환경별 키 관리
개발, 스테이징, 프로덕션마다 API 키와 베이스 URL이 다릅니다. Apidog 환경 기능을 사용하면 같은 API 요청을 환경별 변수로 실행할 수 있습니다.
예:
{{base_url}}/exchange-rate?base=USD&target=KRW
환경별 값:
dev.base_url = https://dev-api.example.com
staging.base_url = https://staging-api.example.com
prod.base_url = https://api.example.com
이 패턴을 사용하면 ADK 도구가 호출하는 API를 배포 단계별로 더 안정적으로 검증할 수 있습니다.
더 자세한 흐름은 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이 가장 먼저 출시되었고 가장 완성도가 높습니다. 이후 Java가 추가되었으며 Go 및 TypeScript 지원도 뒤따랐습니다.
현재 가장 넓은 기능 범위를 원한다면 Python으로 시작하는 것이 안전합니다.
ADK 에이전트가 의존하는 API는 어떻게 테스트하나요?
에이전트와 API를 분리해서 테스트하는 것이 좋습니다.
실무에서는 다음 순서가 유용합니다.
- 도구가 호출할 API의 요청/응답 계약을 정의합니다.
- Apidog에서 목업 응답을 만듭니다.
- 에이전트를 목업 API에 연결합니다.
- 정상 응답, 오류 응답, 빈 응답을 테스트합니다.
- API 단언으로 응답 구조가 깨지지 않는지 검증합니다.
- 실제 API로 전환하기 전에 환경 변수를 정리합니다.
LLM 엔드포인트 테스트 패턴은 ChatGPT API를 테스트하는 방법에서도 확인할 수 있습니다.
마무리
Google ADK는 Gemini 및 Vertex AI와 잘 통합되면서도 다른 모델로 확장할 수 있는 에이전트 프레임워크입니다. 하나의 에이전트와 몇 개의 도구로 시작한 뒤, adk web으로 실행 흐름을 확인하고, 필요할 때 서브 에이전트와 관리형 런타임으로 확장하는 방식이 현실적입니다.
에이전트가 외부 API에 의존한다면 API 응답 계약을 먼저 안정화해야 합니다. 도구가 호출하는 엔드포인트를 목업하고, 응답 구조를 단언하고, 환경별 설정을 관리하는 레이어가 필요합니다. 이 부분을 Apidog로 처리하면 ADK 에이전트의 불안정한 동작을 더 일찍 발견할 수 있습니다.
Top comments (0)