빠른 시작: 에이전트 개발 키트로 에이전트 빌드

이 빠른 시작에서는 Google Cloud 프로젝트 설정, 에이전트 개발 키트(ADK) 설치, 기본 에이전트 설정, 개발자 사용자 인터페이스 실행을 안내합니다.

이 빠른 시작에서는 Python 3.10 이상 및 터미널 액세스 권한이 있는 로컬 IDE(VS Code, PyCharm 등)를 사용한다고 가정합니다 에이전트는 전적으로 사용자 머신에서 실행되므로 로컬 애플리케이션 개발에 권장됩니다.

또한 Python 3.9 이상 또는 Java 17 이상과 터미널 액세스 권한이 있는 로컬 IDE(예: VS Code, PyCharm, IntelliJ IDEA)를 사용한다고 가정하는 이 ADK 빠른 시작을 확인하세요. 이 메서드는 전적으로 애플리케이션을 머신에서 실행하며 내부 개발에 권장됩니다.

시작하기 전에

다음 단계를 완료합니다.

Google Cloud 프로젝트 설정

Google Cloud 프로젝트를 설정하고 Vertex AI API를 사용 설정합니다.

Sign in to your Google Cloud account. If you're new to Google Cloud, create an account to evaluate how our products perform in real-world scenarios. New customers also get $300 in free credits to run, test, and deploy workloads.
In the Google Cloud console, on the project selector page, select or create a Google Cloud project.
Roles required to select or create a project
• Select a project: Selecting a project doesn't require a specific IAM role—you can select any project that you've been granted a role on.
• Create a project: To create a project, you need the Project Creator (roles/resourcemanager.projectCreator), which contains the resourcemanager.projects.create permission. Learn how to grant roles.
Note: If you don't plan to keep the resources that you create in this procedure, create a project instead of selecting an existing project. After you finish these steps, you can delete the project, removing all resources associated with the project.
Go to project selector
Verify that billing is enabled for your Google Cloud project.
Enable the Vertex AI API.
Roles required to enable APIs
To enable APIs, you need the Service Usage Admin IAM role (roles/serviceusage.serviceUsageAdmin), which contains the serviceusage.services.enable permission. Learn how to grant roles.
Enable the API
Make sure that you have the following role or roles on the project: Vertex AI User
Check for the roles
1. In the Google Cloud console, go to the IAM page.

   Go to IAM
2. Select the project.

3. In the Principal column, find all rows that identify you or a group that you're included in. To learn which groups you're included in, contact your administrator.

4. For all rows that specify or include you, check the Role column to see whether the list of roles includes the required roles.
Grant the roles
1. In the Google Cloud console, go to the IAM page.

   IAM으로 이동
2. 프로젝트를 선택합니다.
3. 액세스 권한 부여를 클릭합니다.

4. 새 주 구성원 필드에 사용자 식별자를 입력합니다. 일반적으로 Google 계정의 이메일 주소입니다.

5. 역할 선택 목록에서 역할을 선택합니다.
6. 역할을 추가로 부여하려면 다른 역할 추가를 클릭하고 각 역할을 추가합니다.
7. 저장을 클릭합니다.

In the Google Cloud console, on the project selector page, select or create a Google Cloud project.

Roles required to select or create a project

• Select a project: Selecting a project doesn't require a specific IAM role—you can select any project that you've been granted a role on.
• Create a project: To create a project, you need the Project Creator (roles/resourcemanager.projectCreator), which contains the resourcemanager.projects.create permission. Learn how to grant roles.

Note: If you don't plan to keep the resources that you create in this procedure, create a project instead of selecting an existing project. After you finish these steps, you can delete the project, removing all resources associated with the project.

Go to project selector

Verify that billing is enabled for your Google Cloud project.

Enable the Vertex AI API.

Roles required to enable APIs

To enable APIs, you need the Service Usage Admin IAM role (roles/serviceusage.serviceUsageAdmin), which contains the serviceusage.services.enable permission. Learn how to grant roles.

Enable the API

Make sure that you have the following role or roles on the project: Vertex AI User

Check for the roles

1. In the Google Cloud console, go to the IAM page.

   Go to IAM
2. Select the project.

3. In the Principal column, find all rows that identify you or a group that you're included in. To learn which groups you're included in, contact your administrator.

4. For all rows that specify or include you, check the Role column to see whether the list of roles includes the required roles.

Grant the roles

1. In the Google Cloud console, go to the IAM page.

   IAM으로 이동
2. 프로젝트를 선택합니다.
3. 액세스 권한 부여를 클릭합니다.

4. 새 주 구성원 필드에 사용자 식별자를 입력합니다. 일반적으로 Google 계정의 이메일 주소입니다.

5. 역할 선택 목록에서 역할을 선택합니다.
6. 역할을 추가로 부여하려면 다른 역할 추가를 클릭하고 각 역할을 추가합니다.
7. 저장을 클릭합니다.

사용자 인증 정보를 설정합니다.

로컬 터미널에서 Google Cloud CLI를 설정하고 인증합니다. Google AI Studio의 Gemini API에 익숙한 경우 Vertex AI의 Gemini API는 API 키 대신 Identity and Access Management를 사용하여 액세스를 관리한다는 점에 유의하세요.

1. Google Cloud CLI를 설치하고 초기화합니다.

2. 이전에 gcloud CLI를 설치한 경우 이 명령어를 실행하여 gcloud 구성요소가 업데이트되었는지 확인합니다.

   gcloud components update

3. 다음 명령어를 실행하여 로컬 애플리케이션 기본 사용자 인증 정보(ADC) 파일을 생성합니다. 에이전트는 로컬 애플리케이션 개발 중에 이러한 사용자 인증 정보를 사용하여 Vertex AI에 액세스합니다.

   gcloud auth application-default login

   자세한 내용은 애플리케이션 기본 사용자 인증 정보 설정을 참조하세요.

가상 환경 설정 및 ADK 설치

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

  # Create
  python -m venv .venv
  # Activate (uncomment the line relevant to your environment)
  # macOS/Linux: source .venv/bin/activate
  # Windows CMD: .venv\Scripts\activate.bat
  # Windows PowerShell: .venv\Scripts\Activate.ps1
  

• ADK 설치:

  pip install google-adk
  

에이전트 만들기

터미널을 사용하여 폴더 구조를 만듭니다.

mkdir multi_tool_agent/
touch \
multi_tool_agent/__init__.py \
multi_tool_agent/agent.py \
multi_tool_agent/.env

구조:

parent_folder/
    multi_tool_agent/
        __init__.py
        agent.py
        .env

다음 코드를 복사하여 만든 다음 세 개의 파일에 붙여넣습니다.

• __init__.py

  from . import agent
  

• .env

  # If using Gemini via Vertex AI on Google Cloud
  GOOGLE_CLOUD_PROJECT="your-project-id"
  GOOGLE_CLOUD_LOCATION="your-location" #e.g. us-central1
  GOOGLE_GENAI_USE_VERTEXAI="True"
  

• agent.py

  from google.adk.agents import Agent
  
  def get_weather(city: str) -> dict:
      """Retrieves the current weather report for a specified city.
  
      Returns:
          dict: A dictionary containing the weather information with a 'status' key ('success' or 'error') and a 'report' key with the weather details if successful, or an 'error_message' if an error occurred.
      """
      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."}
  
  def get_current_time(city:str) -> dict:
      """Returns the current time in a specified city.
  
      Args:
          dict: A dictionary containing the current time for a specified city information with a 'status' key ('success' or 'error') and a 'report' key with the current time details in a city if successful, or an 'error_message' if an error occurred.
      """
      import datetime
      from zoneinfo import ZoneInfo
  
      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)
      return {"status": "success",
              "report": f"""The current time in {city} is {now.strftime("%Y-%m-%d %H:%M:%S %Z%z")}"""}
  
  root_agent = Agent(
      name="weather_time_agent",
      model="gemini-2.0-flash",
      description="Agent to answer questions about the time and weather in a city.",
      instruction="I can answer your questions about the time and weather in a city.",
      tools=[get_weather, get_current_time]
  )
  

에이전트에는 모의 구현이 포함된 두 가지 함수 도구가 있습니다.

에이전트 실행 및 테스트

1. 터미널에서 에이전트의 상위 디렉터리로 이동합니다(예: cd .. 사용).

   parent_folder/      <-- navigate to this directory
       multi_tool_agent/
           __init__.py
           agent.py
           .env
   

2. 다음 명령어를 실행하여 개발자 웹 UI를 실행합니다.

   adk web
   

   제공된 URL(일반적으로 http://localhost:8000 또는 http://127.0.0.1:8000)을 브라우저에서 엽니다. 이 연결은 전적으로 로컬 머신에 유지됩니다. multi_tool_agent를 선택하고 에이전트와 상호작용합니다.

참고: 명령줄 인터페이스를 사용하여 에이전트를 실행하고 테스트하려면 adk run multi_tool_agent 명령어를 실행하세요. 예를 들어 로컬 머신에 웹브라우저가 없는 경우에 유용합니다.

사용해 볼 만한 프롬프트 예시

다음과 같은 프롬프트를 사용해 볼 수 있습니다.

• 뉴욕 날씨는 어때?
• 뉴욕은 지금 몇 시야?
• 파리 날씨는 어때?
• 파리는 지금 몇 시야?

다음 단계

• 에이전트에 대해 알아보기

• Agent Engine에 배포