이 페이지는 Cloud Translation API를 통해 번역되었습니다.

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

1. 시작하기 전에

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

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

이 Codelab을 마치면 개인 어시스턴트 에이전트에 다양한 목적의 도구를 제공하여 정교한 멀티 에이전트 시스템 (MAS)으로 변환할 때 이 시리즈의 후속 부분에서 확장할 수 있도록 한 단계 더 나아가게 됩니다.

기본 요건

생성형 AI 개념에 대한 이해
Python 프로그래밍에 대한 기본적인 숙련도
ADK로 AI 에이전트 빌드: 기본사항 Codelab 또는 이와 유사한 Codelab을 완료함

학습할 내용

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

필요한 항목

작동하는 컴퓨터와 안정적인 Wi-Fi
Google Cloud 콘솔에 액세스하기 위한 브라우저(예: Chrome)
호기심과 학습에 대한 열의

무료 체험 결제 계정 사용

이 Codelab을 완료하려면 활성 상태의 Google Cloud 결제 계정도 필요합니다. 아직 없는 경우 다음 단계에 따라 무료 체험 결제 계정을 사용하세요.

브라우저에서 시크릿 창을 엽니다.
이 신청 포털로 이동합니다.
개인 Gmail 계정을 사용하여 로그인합니다.
포털의 단계별 안내를 따릅니다.

2. 소개

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

도구는 AI 어시스턴트가 외부 세계에 액세스할 수 있도록 지원하는 기능이라고 생각하면 됩니다. 계산기, 웹브라우저, 특정 회사 데이터베이스에 대한 액세스 등이 그 예입니다. ADK에서 도구는 에이전트가 실시간 데이터를 조회하거나 외부 API를 호출하는 등의 특정 작업을 실행할 수 있도록 하는 모듈식 코드입니다. 도구를 사용하면 단순한 대화를 훨씬 뛰어넘는 기능을 제공할 수 있습니다.

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

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

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

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

상담사에게 도구를 제공하려면 먼저 사용할 기본 상담사가 필요합니다. 진도에 가장 적합한 학습 과정을 선택하세요.

경로 A: Foundation 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 파일을 만듭니다..

touch 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

에이전트가 작동하면 '싱가포르 달러에서 일본 엔으로의 환율은 얼마야?'라고 다시 질문합니다.

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

환전과 관련된 질문이 있으면 언제든지 물어보세요.

5. 내장 Google 검색 도구와 통합

이제 에이전트가 환율을 제공할 수 있으므로 다음 작업은 다음 달의 일기 예보를 가져오는 것입니다. 에이전트에게 '다음 달 일본 도쿄의 일기예보는 어때?'라고 질문합니다.

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

다행히 에이전트 개발 키트 (ADK)는 Google 검색을 비롯한 다양한 기본 제공 도구를 제공하여 에이전트가 외부 세계와 상호작용하는 방식을 간소화합니다. 다음과 같이 agent.py 파일을 수정하여 Google 검색 도구를 에이전트에 추가해 보겠습니다.

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

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), 
        google_search,
    ]
)

파일을 수정한 후 adk web 인스턴스를 다시 시작합니다. 잊어버릴 수도 있으니

터미널을 클릭하고 Ctrl + C를 눌러 인스턴스를 중지합니다.
uv run adk web을 클릭하여 인스턴스를 시작합니다.
"다음 달 일본 도쿄의 일기 예보는 뭐야?"와 같은 질문을 해 보세요.

이제 실시간 정보가 포함된 응답을 받을 수 있습니다.

이를 위해 다중 에이전트 패턴을 구현할 수도 있습니다. 먼저 Google 검색만 수행하는 전문 에이전트를 만듭니다. 그런 다음 이 새로운 Google 검색 에이전트를 기본 personal_assistant에 도구로 할당합니다. 다음 단계를 따르세요.

`custom_agents.py` 파일 만들기

이제 터미널에서 다음 명령어를 실행하여 personal_assistant 폴더에 custom_agents.py라는 Python 파일을 만듭니다.

touch personal_assistant/custom_agents.py

이제 폴더 구조는 다음과 같습니다.

ai-agents-adk/
└── personal_assistant/
    ├── .env
    ├── __init__.py
    ├── agent.py
    ├── custom_functions.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에서 instruction 필드가 사라진 것을 확인할 수 있습니다. 이제 명령어는 사용 가능한 도구에 의해 암시적으로 정의됩니다.

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

이제 입력합니다.

adk web

터미널에서 인스턴스를 시작하고 에이전트에게 다시 질문합니다. "다음 달 일본 도쿄의 일기 예보는 뭐야?"

이제 상담사가 google_search_agent를 사용하여 최신 정보를 확인합니다.

현재 환전 관련 질문을 해 볼 수도 있습니다. 이제 상담사는 각 질문에 적합한 도구를 사용할 수 있습니다.

상담사에게 실시간 정보가 필요한 다른 질문을 하고 상담사가 사용할 수 있는 도구를 사용하여 질문을 처리하는 방식을 관찰하세요.

6. LangChain의 Wikipedia 도구 활용

우리 상담사가 훌륭한 여행 어시스턴트가 될 수 있도록 노력하고 있습니다. get_fx_rate 도구로 환전을 처리하고 google_search_agent 도구로 물류를 관리할 수 있습니다. 하지만 멋진 여행은 단순히 물류에 관한 것만이 아닙니다. 목적지의 문화와 역사를 이해하는 것도 중요합니다.

google_search_agent는 문화 및 역사적 사실을 찾을 수 있지만, 위키백과와 같은 전용 소스의 정보는 더 체계적이고 신뢰할 수 있는 경우가 많습니다.

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

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

uv pip install langchain-community wikipedia

`third_party_tools.py` 파일 만들기

이제 터미널에서 다음 명령어를 실행하여 personal_assistant 폴더에 third_party_tools.py라는 Python 파일을 만듭니다.

touch 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 도구의 구현이 포함됩니다. Cloud 편집기를 사용하여 다음 코드를 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

터미널에서 인스턴스를 시작하고 에이전트에게 '교토의 역사에 관해 알려 줘'라고 질문합니다.

상담사는 이를 과거 질문으로 올바르게 식별하고 새로운 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을 완벽하게 준비했습니다. 다음 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` 파일 업데이트