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

1. 소개

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

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

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

LLM과 에이전트 비교

브레인 (LLM): 추론, 계획, 자연어 이해를 제공합니다. 해야 할 일을 결정합니다.

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

에이전트 개발 키트 (ADK)

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

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

빌드할 항목

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

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 .

다음과 비슷한 출력이 표시됩니다.

'안녕하세요' 또는 궁금한 점을 입력하세요. 답변은 사람마다 다를 수 있습니다. 이것이 생성형 AI의 특징입니다.

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

adk web

6. 멀티 도구 에이전트

도구는 에이전트가 내부 지식을 넘어 외부 세계와 상호작용할 수 있도록 하는 모듈식 코드 조각(일반적으로 함수 또는 API)입니다.

ADK의 도구 유형

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

이 Codelab에서는 함수 도구를 다룹니다. 이제 에이전트를 발전시켜 멀티 도구로 만들어 보겠습니다.

agent.py에 새 메서드 get_weather를 추가해 보겠습니다.

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 통합

이제 여러 도구를 사용하는 방법을 알았으니 실제 사례를 통해 살펴보겠습니다. 건강한 힌트 에이전트를 만들어 보겠습니다. 여기서의 목표는 성분 목록이 있는 이미지를 에이전트에 업로드하면 에이전트가 건강한 성분과 그렇지 않은 성분을 알려주는 것입니다.

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