ADK: 기본사항부터 멀티 도구 에이전트까지

1. 소개

이 Codelab에서는 기본사항부터 시작하여 멀티 도구 에이전트 개발까지 ADK를 사용하여 에이전트를 빌드하는 방법을 포괄적으로 소개합니다.

가장 간단한 형태의 AI 에이전트는 대규모 언어 모델 (LLM)을 '추론 엔진'으로 사용하여 일련의 작업을 자율적으로 실행하여 목표를 달성하는 소프트웨어 시스템입니다.

LLM이 조언을 제공할 수 있는 유능한 컨설턴트라면 AI 에이전트는 도구를 사용하여 조언을 실행할 수 있는 사전 대응형 엔지니어입니다.

LLM과 에이전트 비교

두뇌 (LLM): 추론, 계획, 자연어 이해를 제공합니다. 수행해야 할 작업을 결정합니다.

손 (도구): 에이전트가 실제 환경과 상호작용할 수 있도록 하는 API, SDK, 커스텀 함수입니다. 계획을 실행합니다.

에이전트 개발 키트 (ADK)

에이전트 개발 키트 (ADK)는 AI 에이전트의 생성, 배포, 조정을 간소화하도록 설계된 전문 프레임워크입니다. 정적 대규모 언어 모델을 코드를 실행하고, API를 호출하고, 다단계 워크플로를 관리할 수 있는 동적 에이전트로 변환하는 데 필요한 표준화된 빌딩 블록을 제공합니다.

멀티 도구 에이전트는 검색 엔진, 데이터베이스, 계산기와 같은 다양한 전문 함수를 선택하고 순서 지정하여 복잡한 문제를 해결할 수 있는 오케스트레이터입니다. 각 단계에 사용할 도구를 지능적으로 결정하고 한 작업의 출력을 다음 작업의 입력으로 전달하여 최종 목표를 달성할 수 있습니다.

빌드할 항목

이 Codelab에서는 간단한 텍스트 추론에서 멀티 도구 파워하우스로 전환되는 지능형 영양 컨설턴트인 'Healthy Hints' 에이전트를 빌드합니다. 영양 개념을 이해하는 기본적인 대화형 에이전트를 만든 다음 점진적으로 스토리지 SDK 도구를 사용하여 재료 이미지를 보관하고 Vision 도구를 사용하여 이러한 이미지를 '읽고' 분석합니다. 이 실습이 끝나면 음식 라벨의 업로드된 사진을 가져와 기록 보관을 위해 클라우드 버킷에 저장하고 각 재료에 대한 'Healthy Hints'를 즉시 제공할 수 있는 완전한 기능을 갖춘 오케스트레이터가 완성됩니다.

2. 기본 요건

결제가 사용 설정된 Google Cloud 프로젝트
웹 브라우저

프로젝트 만들기

Google Cloud 콘솔의 프로젝트 선택기 페이지에서 Google Cloud 프로젝트를 선택하거나 만듭니다.
Cloud 프로젝트에 결제가 사용 설정되어 있는지 확인합니다. 프로젝트에 결제가 사용 설정되어 있는지 확인하는 방법을 알아보세요.

Cloud Shell 활성화

필요한 언어가 미리 로드되어 설치된 Google Cloud 콘솔에서 실행되는 명령줄 환경인 Cloud Shell을 사용합니다. Cloud 콘솔에서 오른쪽 상단에 있는 Cloud Shell 활성화 를 클릭합니다.

Cloud Shell에 연결되면 이미 인증이 완료되어 있으며 프로젝트가 프로젝트 ID로 설정된 것을 볼 수 있습니다. Cloud Shell에서 다음 명령어를 실행하여 인증되었는지 확인합니다.

gcloud auth list

Cloud Shell에서 다음 명령어를 실행하여 gcloud 명령어가 프로젝트를 알고 있는지 확인합니다.

gcloud config list project

프로젝트가 설정되지 않은 경우 다음 명령어를 사용하여 설정합니다.

gcloud config set project <YOUR_PROJECT_ID>

gcloud 명령어 및 사용법은 문서를 참조하세요.

편집기 열기

이 Codelab에서는 기본 제공 Cloud 편집기를 사용합니다. Cloud Shell 창에서 오른쪽 상단에 있는 편집기 열기 버튼을 클릭합니다. 그러면 VSCode 편집기가 열립니다.

3. ADK 설정

이전 섹션에서 활성화한 Cloud Shell 터미널로 이동해 보겠습니다.

가상 환경 만들기 및 활성화 (권장)

Cloud Shell 터미널에서 가상 환경을 만듭니다.

python -m venv .venv

가상 환경을 활성화합니다.

source .venv/bin/activate

ADK 설치

pip install google-adk

4. Google API 키

AI Studio를 사용하여 Google API 키를 만듭니다.

https://aistudio.google.com/을 방문하고 왼쪽 하단 메뉴에서 Get API Key를 클릭합니다.

API 키 창이 표시되면 이 창에서 API 키 만들기를 클릭합니다.

새 키를 만드는 팝업이 표시됩니다. 키 이름을 healthy-hints-key로 지정합니다.

'가져온 프로젝트 선택' 드롭다운으로 이동합니다.

Import Project를 클릭하면 모든 Google Cloud 프로젝트가 나열된 측면 창이 표시됩니다. 작업할 프로젝트를 선택합니다.

가져오기를 클릭합니다.

이제 드롭다운이 방금 가져온 프로젝트로 업데이트됩니다. 드롭다운에서 프로젝트를 선택합니다. '지금 키 만들기'를 클릭합니다. 이제 생성된 API 키 목록이 표시됩니다. 방금 만든 API 키의 복사 아이콘을 클릭합니다.

5. 샘플 에이전트

Cloud Shell 터미널에서 원하는 프로젝트 위치에 에이전트의 루트 디렉터리를 만듭니다.

adk create healthy_hints

모델을 선택할 수 있지만 이 Codelab에서는 gemini-2.5-flash를 사용합니다.

이 Codelab에서는 Google AI를 사용합니다. 이전 단계에서 만든 API 키를 붙여넣습니다.

방금 만든 폴더를 열어 보겠습니다. 가장 왼쪽 메뉴에서 아이콘 을 클릭하고 파일 -> 폴더 열기를 클릭합니다. 방금 생성된 healthy_hints 폴더를 선택합니다. 이 폴더는 일반적으로 /home/<username> 폴더에 있습니다.
healthy_hints 폴더 구조는 일반적으로 다음과 같습니다.

Google API 키가 포함된 .env 파일이 표시됩니다. 이 파일을 사용하여 환경 변수를 설정할 수 있습니다.
`agent.py`라는 다른 파일도 생성되며 이 파일이 기본 에이전트 파일입니다. 여기에서 샘플 루트 에이전트가 생성됩니다. 이 파일의 콘텐츠를 자세히 살펴보겠습니다. 먼저 ADK에서 llm_agent를 가져옵니다. 그런 다음 ADK DSL을 사용하여 루트 에이전트를 만듭니다. 모델 이름을 Gemini-2.5-flash로 지정하고, 에이전트 이름을 지정하고, 에이전트에 대한 설명을 제공합니다. 여기에서 가장 중요한 것은 명령어입니다. 여기에서 에이전트가 자연어로 수행해야 할 작업을 알려줍니다.
이 샘플 에이전트는 매우 일반적이며 사용자의 질문에 답변하기만 합니다.
이제 이 에이전트를 로컬에서 실행해 보겠습니다. 이 에이전트와 상호작용할 수 있는 방법은 CLI와 웹의 두 가지입니다.
CLI: healthy_hints 디렉터리 외부에서 다음 명령어를 실행합니다.

adk run healthy_hints

또는 healthy_hints 디렉터리 내부에 있는 경우 다음 명령어를 실행합니다.

adk run .

다음과 비슷한 결과가 출력됩니다.

'hi' 또는 궁금한 점을 작성합니다. 답변은 사람마다 다를 수 있습니다. 이것이 생성형 AI의 특성입니다.

웹: healthy_hints의 상위 디렉터리에서 다음 명령어를 실행합니다.

adk web

6. 멀티 도구 에이전트

도구는 일반적으로 함수 또는 API인 모듈식 코드 조각으로, 에이전트가 내부 지식을 넘어 환경과 상호작용할 수 있도록 합니다.

ADK의 도구 유형

함수 도구: 직접 작성하는 커스텀 로직입니다. 예를 들어 특정 데이터베이스에 연결하는 함수 또는 회사의 고유한 형식에 맞는 커스텀 '로그 파서'입니다.
기본 제공 도구: Google 검색, 코드 인터프리터 또는 Google RAG 엔진과 같이 Google 또는 ADK에서 제공하는 바로 사용할 수 있는 기능입니다.
Agents-as-Tools: 고급 '멀티 도구' 또는 '멀티 에이전트' 시스템에서 하나의 전문 에이전트가 다른 에이전트의 도구 역할을 할 수 있습니다. 예를 들어 '검색 에이전트'는 '조사 관리자 에이전트'에서 사용하는 도구가 될 수 있습니다.

이 Codelab에서는 함수 도구를 다룹니다. 이제 에이전트를 고급화하고 멀티 도구로 만들어 보겠습니다.

agent.py

def get_weather(city: str) -> dict:
  """Retrieves the current weather report for a specified city.

  Args:
    city (str): The name of the city for which to retrieve the weather report.

  Returns:
    dict: status and result or error msg.
  """
  if city.lower() == "new york":
    return {
      "status": "success",
      "report": (
          "The weather in New York is sunny with a temperature of 25 degrees"
          " Celsius (77 degrees Fahrenheit)."
      ),
    }
  else:
    return {
      "status": "error",
      "error_message": f"Weather information for '{city}' is not available.",
    }

agent.py를 수정하고 에이전트의 이름, 설명, 명령어를 변경해 보겠습니다.

root_agent = Agent(
    model='gemini-2.5-flash',
    name='healthy_hints_agent',
    description='Agent to answer questions about the weather in a city.',
    instruction='You are a helpful agent who can answer user questions about the weather in a city.',
    tools=[get_weather],
)

지금까지 도구를 하나만 만들었습니다. 이제 여러 도구를 만들어 보겠습니다.

get_current_time이라는 다른 메서드를 만들어 보겠습니다.

def get_current_time(city: str) -> dict:
  """Returns the current time in a specified city.

  Args:
    city (str): The name of the city for which to retrieve the current time.

  Returns:
    dict: status and result or error msg.
  """

  if city.lower() == "new york":
    tz_identifier = "America/New_York"
  else:
    return {
      "status": "error",
      "error_message": (
        f"Sorry, I don't have timezone information for {city}."
      ),
    }

  tz = ZoneInfo(tz_identifier)
  now = datetime.datetime.now(tz)
  report = (
    f'The current time in {city} is {now.strftime("%Y-%m-%d %H:%M:%S %Z%z")}'
  )
  return {"status": "success", "report": report}

이 도구를 호출하도록 에이전트를 수정해 보겠습니다.

root_agent = Agent(
  model='gemini-2.5-flash',
  name='healthy_hints_agent',
  description='Agent to answer questions about the time and weather in a city.',
  instruction='You are a helpful agent who can answer user questions about the time and weather in a city.',
  tools=[get_weather, get_current_time],
)

설명, 명령어, 도구를 적절히 수정했습니다. 이제 이 업데이트된 에이전트를 실행해 보겠습니다. 이번에는 에이전트가 현재 시간과 날씨도 응답합니다.

7. SDK 통합

이제 여러 도구를 사용하는 방법을 알았습니다. 실제 사례를 살펴보겠습니다. Healthy Hints 에이전트를 만들어 보겠습니다. 여기서의 목표는 재료 목록이 있는 이미지를 에이전트에 업로드하면 에이전트가 각 재료가 건강에 좋은지 여부를 알려주는 것입니다.

먼저 Google Cloud Storage에 이미지를 업로드할 버킷을 만들어 보겠습니다. 새 탭을 열고 https://console.cloud.google.com/으로 이동한 후 검색창에 'cloud storage'를 입력합니다. 이제 제품 및 페이지에서 Cloud Storage를 선택합니다.

그러면 Google Cloud Storage의 개요 페이지로 이동합니다. Create bucket 버튼을 클릭합니다. 버킷 만들기 페이지에서 버킷 이름을 입력합니다. 이름은 무엇이든 가능하지만 이 Codelab에서는 healthy-hints-bucket-kolkata로 지정합니다 . 다른 모든 항목은 그대로 두고 Create 버튼을 클릭합니다.

requirements.txt라는 새 파일을 만들고 google-cloud-storage를 추가해 보겠습니다. Python Storage SDK를 사용하여 스토리지에 이미지를 업로드합니다.

먼저 종속 항목을 설치해 보겠습니다.

pip install -r requirements.txt

먼저 Storage API를 사용 설정해야 할 수 있습니다. 터미널에서 다음 명령어를 실행하여 이 작업을 수행합니다.

gcloud services enable storage.googleapis.com

이제 이미지를 업로드하는 새 도구를 추가해 보겠습니다.

def upload_image() -> str:
  storage_client = storage.Client()
  bucket_name = "healthy-hints-bucket-kolkata"
  bucket = storage_client.bucket(bucket_name)
  blob = bucket.blob("ingredirents")
  blob.upload_from_filename(<image-file-path>)

이제 새 도구를 사용하도록 에이전트를 업데이트해 보겠습니다.

root_agent = Agent(
  model='gemini-2.5-flash',
  name='healthy_hints_agent',
  description='Agent to upload image to Google Cloud Storage',
  instruction='You are a helpful agent who will upload the image to Google Cloud Storage using `upload_image` tool.',
  tools=[upload_image],
)

이제 이미지에서 재료를 읽는 다른 도구를 추가해 보겠습니다. requirements.txt에 google-cloud-vision을 추가하고 새 종속 항목을 설치해 보겠습니다.

pip install -r requirements.txt

다시 말하지만 먼저 Vision API를 사용 설정해야 할 수 있습니다. 터미널에서 다음 명령어를 실행하여 이 작업을 수행합니다.

gcloud services enable vision.googleapis.com

이제 새 도구 read_ingredients를 추가해 보겠습니다.

def read_ingredients() -> str:
  vision_client = vision.ImageAnnotatorClient()

  with io.open("/home/bajajnehaa/healthy_hints/images/Ingredients-list.jpg", 'rb') as image_file:
    content = image_file.read()

  image = vision.Image(content=content)
  response = vision_client.text_detection(image=image)
  texts = response.text_annotations
  return texts[0].description

이제 이 도구를 사용하도록 에이전트를 업데이트해 보겠습니다.

root_agent = Agent(
  model='gemini-2.5-flash',
  name='healthy_hints_agent',
  description='Agent to upload image to Google Cloud Storage, read the list of ingredients from the image and explain if the ingredient is healthy or not',
  instruction='You are a helpful agent who will upload the image to Google Cloud Storage using `upload_image` tool, read the ingredients of the image using `read_ingredients` tool and explain if the ingredient is healthy or not in one line.',
  tools=[upload_image, read_ingredients],
)

8. 결론

Healthy Hints Codelab을 완료했습니다. 표준 AI를 텍스트 생성기에서 사전 대응형 멀티 도구 에이전트로 성공적으로 변환했습니다. ADK를 사용하여 Vision API와 Cloud Storage SDK를 통합함으로써 에이전트에게 라벨을 읽는 '눈'과 라벨을 보관하는 '메모리'를 제공했습니다. 에이전트가 파일을 저장할 시점을 자율적으로 결정하고 원시 데이터를 해석하여 실제 건강 조언을 제공하는 방법을 살펴보았습니다.

앞으로 이러한 원칙은 모든 자동화된 시스템의 청사진 역할을 합니다. 클라우드 인프라를 관리하든 개인 비서를 빌드하든 핵심은 동일합니다. 전문 도구를 정의하고 에이전트가 로직을 조정하도록 합니다. 다음 단계로 '영양 데이터베이스' 또는 '이메일 도구'와 같은 도구를 더 추가하여 에이전트의 영향을 확대해 보세요.

ADK: 기본사항부터 멀티 도구 에이전트까지 컬렉션을 사용해 정리하기 내 환경설정을 기준으로 콘텐츠를 저장하고 분류하세요.