ADK로 AI 에이전트 빌드: 도구로 역량 강화

1. 시작하기 전에

'ADK를 사용한 AI 에이전트 빌드' 시리즈의 두 번째 파트에 오신 것을 환영합니다. 이 실습 Codelab에서는 다양한 도구를 사용하여 기본 AI 에이전트를 지원합니다.

시작하려면 이 가이드에서 두 가지 경로를 제공합니다. 하나는 'ADK를 사용한 AI 에이전트 빌드: 기초' Codelab에서 계속하는 사용자를 위한 경로이고 다른 하나는 새로 시작하는 사용자를 위한 경로입니다. 두 경로 모두 시작하는 데 필요한 기본 에이전트 코드를 제공합니다.

이 Codelab을 마치면 다양한 용도로 사용할 수 있는 도구를 사용하여 개인 어시스턴트 에이전트를 지원하게 됩니다. 이 에이전트는 이 시리즈의 후속 파트에서 정교한 멀티 에이전트 시스템 (MAS)으로 변환되면서 확장될 준비가 됩니다.

이 단축 URL(goo.gle/adk-using-tools)을 통해 이 Codelab에 액세스할 수도 있습니다.

기본 요건

생성형 AI 개념에 대한 이해
Python 프로그래밍에 대한 기본적인 지식 숙지
ADK를 사용한 AI 에이전트 빌드: 기초 Codelab 또는 이와 유사한 Codelab 완료

학습할 내용

커스텀 Python 함수를 도구로 빌드하여 에이전트에 새로운 기술을 제공합니다.
Google 검색과 같은 기본 제공 도구를 사용하여 에이전트를 실시간 정보에 연결합니다.
복잡한 작업을 위한 특수 하위 에이전트를 만들어 멀티 도구 에이전트를 구성합니다.
LangChain과 같은 인기 있는 AI 프레임워크의 도구를 통합하여 기능을 빠르게 확장합니다.

필요한 항목

작동하는 컴퓨터와 안정적인 Wi-Fi
Chrome과 같은 브라우저를 사용하여 Google Cloud 콘솔에 액세스
호기심과 학습 의지

2. 소개

ADK로 빌드된 기본 에이전트에는 강력한 LLM 브레인이 있지만 학습 날짜 이후에 생성된 정보에 액세스할 수 없고 외부 서비스와 상호작용할 수 없다는 제한사항도 있습니다. 전화나 인터넷이 없는 도서관에 갇힌 똑똑하고 책에 박식한 어시스턴트와 같습니다. 에이전트를 진정으로 유용하게 만들려면 도구를 제공해야 합니다.

도구는 AI 어시스턴트에게 외부 세계에 대한 액세스 권한을 부여하는 것으로 생각하면 됩니다. 계산기, 웹브라우저 또는 특정 회사 데이터베이스에 대한 액세스 권한을 부여하는 것과 같습니다. ADK에서 도구는 에이전트가 실시간 데이터 조회 또는 외부 API 호출과 같은 특정 작업을 실행할 수 있도록 하는 모듈식 코드입니다. 도구를 사용하면 단순한 대화를 훨씬 뛰어넘는 기능을 확장할 수 있습니다.

ADK는 세 가지 카테고리의 도구를 제공합니다.

함수 도구: 사전 정의된 함수 및 에이전트와 같이 애플리케이션의 고유한 요구사항을 충족하기 위해 개발하는 커스텀 도구입니다.
기본 제공 도구: Google 검색 및 코드 실행과 같은 일반적인 작업을 위해 프레임워크에서 제공하는 바로 사용할 수 있는 도구입니다.
서드 파티 도구: Serper와 같은 인기 있는 외부 라이브러리, LangChain 및 CrewAI의 도구입니다.

ADK 에이전트와 함께 도구를 사용하는 방법을 자세히 알아보려면 공식 문서를 참고하세요. 이 Codelab에서는 도구를 추가하여 간단한 에이전트를 유능한 개인 여행 어시스턴트로 변환합니다. 지금부터 시작하겠습니다

3. 시작하기: 기본 에이전트

도구를 사용하여 에이전트를 지원하려면 먼저 사용할 기본 에이전트가 필요합니다. 진행 상황에 가장 적합한 경로를 선택하세요.

경로 A: 기초 Codelab에서 계속

'ADK를 사용한 AI 에이전트 빌드: 기초' Codelab을 완료한 경우 모든 설정이 완료된 것입니다. 기존 ai-agents-adk 프로젝트 디렉터리에서 계속 작업할 수 있습니다.

경로 B: 새로 시작

이 Codelab을 직접 시작하는 경우 다음 4단계를 완료하여 환경을 설정하고 필요한 스타터 에이전트를 만드세요.

단계를 완료하면 학습 여정을 시작할 준비가 됩니다.

4. 환전용 맞춤 도구 빌드

이 단계에서는 ADK를 사용하여 간단한 AI 에이전트를 빌드하고 개발 UI에서 실행하는 방법을 이미 알고 있어야 합니다.

다음 달 일본 여행을 준비하고 있고 현재 환율을 확인해야 한다고 가정해 보겠습니다. 에이전트에게 "싱가포르 달러의 일본 엔화 환율은 얼마야?"라고 물어봅니다.

에이전트가 실시간 환율을 가져올 수 없다는 것을 알 수 있습니다. 이는 에이전트가 현재 인터넷 액세스 권한과 외부 시스템 연결이 없기 때문입니다. 에이전트가 값을 반환하더라도 환각일 가능성이 높으므로 해당 값을 신뢰하기 어렵습니다.

이 문제를 해결하기 위해 REST API를 통해 환율을 가져오는 Python 함수를 구현하고 에이전트의 함수 도구 로 통합합니다.

터미널 창에서 단축키 Ctrl + C 를 사용하여 실행 중인 에이전트 프로세스를 종료합니다.

`custom_functions.py` 파일 만들기

터미널에서 이 명령어를 실행하여 personal_assistant 폴더에 custom_functions.py라는 Python 파일을 만들고 코드 편집기에서 엽니다.

cloudshell edit personal_assistant/custom_functions.py

이제 폴더 구조가 다음과 같이 표시됩니다.

ai-agents-adk/
└── personal_assistant/
    ├── .env
    ├── __init__.py
    ├── agent.py
    └── custom_functions.py

이 custom_functions.py 파일에는 외부 API에서 환율 데이터를 가져오는 Python 함수가 포함됩니다. 다음 코드를 복사하여 파일에 붙여넣습니다.

import requests

# define a function to get exchange rate
def get_fx_rate(base: str, target: str):
        """
        Fetches the current exchange rate between two currencies.

        Args:
                base: The base currency (e.g., "SGD").
                target: The target currency (e.g., "JPY").

        Returns:
                The exchange rate information as a json response,
                or None if the rate could not be fetched.
        """
        base_url = "https://hexarate.paikama.co/api/rates/latest"
        api_url = f"{base_url}/{base}?target={target}"

        response = requests.get(api_url)
        if response.status_code == 200:
                return response.json()

이제 agent.py 파일을 수정합니다. get_fx_rate 함수를 가져와 FunctionTool로 할당합니다.

`agent.py` 파일 업데이트

이 코드 블록을 복사하고 agent.py 파일의 기존 콘텐츠를 바꿉니다.

from google.adk.agents import Agent
from google.adk.tools import FunctionTool

from .custom_functions import get_fx_rate

root_agent = Agent(
    model='gemini-2.5-flash',
    name='root_agent',
    description='A helpful assistant for user questions.',
    instruction='Answer user questions to the best of your knowledge',
    tools=[FunctionTool(get_fx_rate)]
)

변경 후 다음을 입력하여 에이전트를 다시 시작합니다.

adk web --allow_origins "regex:https://.*\.cloudshell\.dev"

에이전트가 실행되면 동일한 질문인 "싱가포르 달러의 일본 엔화 환율은 얼마야?"를 다시 물어봅니다.

이번에는 get_fx_rate 도구에서 제공하는 실제 환율이 표시됩니다.

원하는 대로 환전 관련 질문을 자유롭게 하세요.

5. 기본 제공 Google 검색 도구와 통합

이제 에이전트가 환율을 제공할 수 있으므로 다음 태스크는 다음 달의 일기예보를 가져오는 것입니다. 에이전트에게 "다음 달 일본 도쿄의 일기예보는 어때?" 라고 물어봅니다.

예상대로 일기예보에는 에이전트가 보유하지 않은 실시간 정보가 필요합니다. 실시간 데이터가 필요한 각 사용 사례에 대해 새로운 Python 함수를 코딩할 수 있지만 커스텀 도구를 계속 추가하면 에이전트가 너무 복잡해지고 관리하기 어려워집니다.

다행히 에이전트 개발 키트 (ADK)는 Google 검색을 비롯한 바로 사용할 수 있는 기본 제공 도구 모음을 제공하여 에이전트가 외부 세계와 상호작용하는 방식을 간소화합니다.

에이전트에 Google 검색 도구를 제공하려면 멀티 에이전트 패턴을 구현해야 합니다. 먼저 Google 검색을 수행하는 것이 유일한 작업인 특수 에이전트를 만듭니다. 그런 다음 이 새 Google 검색 에이전트 를 기본 personal_assistant에 도구로 할당합니다. 다음 단계를 따르세요.

`custom_agents.py` 파일 만들기

터미널에서 이 명령어를 실행하여 Python 파일을 만들고 custom_agents.py라는 이름으로 personal_assistant 폴더에 저장한 다음 코드 편집기에서 엽니다.

cloudshell edit personal_assistant/custom_agents.py

이제 폴더 구조가 다음과 같이 표시됩니다.

ai-agents-adk/
└── personal_assistant/
    ├── .env
    ├── __init__.py
    ├── agent.py
    ├── custom_functions.py
    └── custom_agents.py

이 custom_agents.py 파일에는 특수 google_search_agent의 코드가 포함됩니다. 다음 코드를 custom_agents.py 파일에 복사합니다.

from google.adk.agents import Agent
from google.adk.tools import google_search


# Create an agent with google search tool as a search specialist
google_search_agent = Agent(
    model='gemini-2.5-flash',
    name='google_search_agent',
    description='A search agent that uses google search to get latest information about current events, weather, or business hours.',
    instruction='Use google search to answer user questions about real-time, logistical information.',
    tools=[google_search],
)

파일이 생성되면 아래와 같이 agent.py 파일을 업데이트합니다.

`agent.py` 파일 업데이트

이 코드 블록을 복사하고 agent.py 파일의 기존 콘텐츠를 바꿉니다.

from google.adk.agents import Agent
from google.adk.tools import FunctionTool
from google.adk.tools.agent_tool import AgentTool

from .custom_functions import get_fx_rate
from .custom_agents import google_search_agent


root_agent = Agent(
    model='gemini-2.5-flash',
    name='root_agent',
    description='A helpful assistant for user questions.',
    tools=[
        FunctionTool(get_fx_rate), 
        AgentTool(agent=google_search_agent),
    ]
)

코드의 강력한 새 패턴을 분석해 보겠습니다.

새로운 전문가 에이전트: 완전히 새로운 에이전트인 google_search_agent를 정의했습니다. 특정 설명과 유일한 도구가 google_search라는 점에 유의하세요. 검색 전문가입니다.
agent_tool.AgentTool: ADK의 특수 래퍼입니다. 전체 에이전트 (google_search_agent)를 가져와 표준 도구처럼 보이도록 패키징합니다.
더 스마트한 **root_agent**: 이제 root_agent에 새 도구인 AgentTool(agent=google_search_agent)가 있습니다. 웹 검색 방법을 알지는 못하지만 검색 작업을 위임할 수 있는 도구가 있다는 것을 알고 있습니다.

root_agent에서 요청 사항 필드가 사라진 것을 알 수 있습니다. 이제 요청 사항은 사용 가능한 도구에 의해 암시적으로 정의됩니다.

root_agent는 사용자의 요청을 이해하고 get_fx_rate 함수 또는 google_search_agent 중 올바른 도구에 전달하는 것이 주요 작업인 오케스트레이터 또는 라우터가 되었습니다. 이 분산 설계는 유지보수가 가능한 복잡한 에이전트 시스템을 빌드하는 데 핵심입니다.

이제 터미널에서 이 명령어를 입력하여 인스턴스를 시작합니다.

adk web --allow_origins "regex:https://.*\.cloudshell\.dev"

에이전트가 실행되면 에이전트에게 "다음 달 일본 도쿄의 일기예보는 어때?" 라고 다시 물어봅니다.

이제 에이전트가 google_search_agent를 사용하여 최신 정보를 가져옵니다.

현재 환율에 관한 질문도 해볼 수 있습니다. 이제 에이전트가 각 질문에 적합한 도구를 사용할 수 있어야 합니다.

실시간 정보가 필요한 다른 질문을 에이전트에게 하고 에이전트가 사용 가능한 도구를 사용하여 쿼리를 처리하는 방법을 관찰해 보세요.

6. LangChain의 Wikipedia 도구 활용

에이전트가 훌륭한 여행 어시스턴트가 되기 위해 노력하고 있습니다. get_fx_rate 도구를 사용하여 환전을 처리하고 google_search_agent 도구를 사용하여 물류를 관리할 수 있습니다. 하지만 훌륭한 여행은 물류뿐만 아니라 목적지의 문화와 역사를 이해하는 것도 중요합니다.

google_search_agent는 문화적, 역사적 사실을 찾을 수 있지만 Wikipedia와 같은 전용 소스의 정보는 더 구조화되고 신뢰할 수 있는 경우가 많습니다.

다행히 ADK는 확장성이 높도록 설계되어 CrewAI 및 LangChain과 같은 다른 AI 에이전트 프레임워크의 도구를 원활하게 통합할 수 있습니다. 이 상호 운용성은 개발 시간을 단축하고 기존 도구를 재사용할 수 있으므로 매우 중요합니다. 이 사용 사례에서는 LangChain의 Wikipedia 도구를 활용합니다.

먼저 실행 중인 에이전트 프로세스 (Ctrl + C)를 중지하고 터미널에 다음 명령어를 입력하여 현재 Python 가상 환경에 추가 라이브러리를 설치합니다.

uv pip install langchain-community wikipedia

`third_party_tools.py` 파일 만들기

다음 명령어는 Python 파일을 만들고 third_party_tools.py라는 이름으로 personal_assistant 폴더에 저장한 후 Cloud 편집기에서 엽니다.

cloudshell edit personal_assistant/third_party_tools.py

이제 폴더 구조가 다음과 같이 표시됩니다.

ai-agents-adk/
└── personal_assistant/
    ├── .env
    ├── __init__.py
    ├── agent.py
    ├── custom_functions.py
    ├── custom_agents.py
    └── third_party_tools.py

이 파일에는 LangChain Wikipedia 도구의 구현이 포함됩니다. 다음 코드를 third_party_tools.py 파일에 복사합니다**.**

from langchain_community.tools import WikipediaQueryRun
from langchain_community.utilities import WikipediaAPIWrapper

# Configure the Wikipedia LangChain tool to act as our cultural guide
langchain_wikipedia_tool = WikipediaQueryRun(
    api_wrapper=WikipediaAPIWrapper(top_k_results=1, doc_content_chars_max=3000)
)

# Give the tool a more specific description for our agent
langchain_wikipedia_tool.description = (
    "Provides deep historical and cultural information on landmarks, concepts, and places."
    "Use this for 'tell me about' or 'what is the history of' type questions."
)

`agent.py` 파일 업데이트

이제 아래 콘텐츠로 agent.py 파일을 업데이트합니다.

from google.adk.agents import Agent
from google.adk.tools import FunctionTool
from google.adk.tools.agent_tool import AgentTool
from google.adk.tools.langchain_tool import LangchainTool

from .custom_functions import get_fx_rate
from .custom_agents import google_search_agent
from .third_party_tools import langchain_wikipedia_tool


root_agent = Agent(
    model='gemini-2.5-flash',
    name='root_agent',
    description='A helpful assistant for user questions.',
    tools=[
        FunctionTool(get_fx_rate), 
        AgentTool(agent=google_search_agent),
        LangchainTool(langchain_wikipedia_tool),
    ]
)

이제 터미널에서 이 명령어를 입력하여 인스턴스를 시작합니다.

adk web --allow_origins "regex:https://.*\.cloudshell\.dev"

에이전트가 준비되면 에이전트에게 "교토의 역사에 대해 알려 줘"라고 물어봅니다.

에이전트는 이를 역사적 쿼리로 올바르게 식별하고 새 Wikipedia 도구를 사용합니다. 서드 파티 도구를 통합하고 특정 역할을 부여함으로써 에이전트를 여행 계획 목적으로 훨씬 더 지능적이고 유용하게 만들었습니다.

에이전트가 이 선택을 한 방법을 정확히 확인하려면 adk web UI 의 이벤트 검사기를 사용하면 됩니다. 이벤트 탭을 클릭한 다음 가장 최근의 functionCall 이벤트를 클릭합니다.

검사기에는 사용 가능한 모든 도구 목록이 표시되고 에이전트가 실행한 도구의 tool_code가 강조표시됩니다.

7. 삭제 (선택사항)

이 Codelab에는 장기 실행 제품이 포함되지 않으므로 터미널에서 Ctrl + C를 눌러 활성 에이전트 세션 (예: 터미널의 adk web 인스턴스)을 중지하는 것으로 충분합니다.

에이전트 프로젝트 폴더 및 파일 삭제

Cloud Shell 환경에서 코드만 삭제하려면 다음 명령어를 사용하세요.

cd ~
rm -rf ai-agents-adk

Vertex AI API 사용 중지

이전에 사용 설정한 Vertex AI API를 사용 중지하려면 이 명령어를 실행하세요.

gcloud services disable aiplatform.googleapis.com

전체 Google Cloud 프로젝트 종료

Google Cloud 프로젝트를 완전히 종료하려면 공식 가이드에서 자세한 안내를 참고하세요.

8. 결론

축하합니다. 커스텀 함수와 실시간 Google 검색 액세스를 사용하여 개인 어시스턴트 에이전트를 성공적으로 지원했습니다. Google ADK와 함께 도구를 사용하는 방법에 관한 공식 문서를 읽어보세요.

더 중요한 것은 유능한 에이전트를 빌드하기 위한 기본 아키텍처 패턴인 특수 에이전트를 도구로 사용하는 방법을 배웠다는 것입니다. 전용 google_search_agent를 만들고 root_agent에 제공함으로써 단일 에이전트 빌드에서 간단하면서도 강력한 멀티 에이전트 시스템 오케스트레이션으로 첫걸음을 내디뎠습니다.

이제 시리즈의 다음 Codelab (출시 예정)을 완벽하게 준비했습니다. 여기에서는 여러 에이전트와 워크플로를 오케스트레이션하는 방법을 자세히 알아봅니다. 시작 세션에서 뵙겠습니다.

ADK로 AI 에이전트 빌드: 도구로 역량 강화

1. 시작하기 전에

기본 요건

학습할 내용

필요한 항목

2. 소개

3. 시작하기: 기본 에이전트

4. 환전용 맞춤 도구 빌드

custom_functions.py 파일 만들기

agent.py 파일 업데이트

5. 기본 제공 Google 검색 도구와 통합

custom_agents.py 파일 만들기

agent.py 파일 업데이트

6. LangChain의 Wikipedia 도구 활용

third_party_tools.py 파일 만들기

agent.py 파일 업데이트

7. 삭제 (선택사항)

에이전트 프로젝트 폴더 및 파일 삭제

Vertex AI API 사용 중지

전체 Google Cloud 프로젝트 종료

8. 결론

`custom_functions.py` 파일 만들기

`agent.py` 파일 업데이트

`custom_agents.py` 파일 만들기

`agent.py` 파일 업데이트

`third_party_tools.py` 파일 만들기

`agent.py` 파일 업데이트