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

ADK로 멀티 에이전트 시스템을 만들고, 에이전트 엔진에 배포하고, A2A 프로토콜을 시작하세요.

1. 이 실습의 목표

이 실습에서는 프롬프트를 기반으로 이미지를 생성하고 프롬프트에 대해 이미지를 평가하는 다중 에이전트 애플리케이션을 빌드합니다. 이미지가 프롬프트에 설명된 요구사항을 충족하지 않으면 요구사항을 충족하는 이미지가 생성될 때까지 에이전트가 계속 이미지를 생성합니다. 이 실습의 각 에이전트는 단일 목적을 가지며, 에이전트는 전체 목표를 달성하기 위해 서로 협력합니다.

학습할 내용

ADK의 기본사항을 이해하고 멀티 에이전트 시스템을 만드는 방법을 알아봅니다.
GCP에서 에이전트를 쉽게 배포하고 사용하는 방법을 알아봅니다.
A2A 프로토콜의 기본사항 이해
A2A 프로토콜과 ADK를 함께 사용하여 개방형 에이전트를 만드는 방법을 알아보세요.

2. 시작하기 전에

사용할 수 있는 프로젝트가 아직 없으면 GCP 콘솔에서 새 프로젝트를 만들어야 합니다.
이 실습에서는 GCP Cloud Shell을 사용하여 작업을 실행합니다. Cloud Shell을 열고 Cloud Shell을 사용하여 프로젝트를 설정합니다.
Cloud Shell 편집기 버튼을 눌러 GCP Cloud Shell 편집기를 엽니다. '셸 승인' 팝업이 표시되면 클릭하여 Cloud Shell 편집기를 승인합니다.
다음 명령어를 사용하여 프로젝트가 이미 인증되었는지 확인할 수 있습니다.

gcloud auth list

Cloud Shell에서 다음 명령어를 실행하여 프로젝트를 확인합니다.

gcloud config list project

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

gcloud config set project <YOUR_PROJECT_ID>

이 실습을 실행하려면 몇 가지 서비스를 사용 설정해야 합니다. Cloud Shell에서 다음 명령어를 실행합니다.

gcloud services enable aiplatform.googleapis.com

3. 개요: Agent Development Kit의 이점

Agent Development Kit은 에이전트형 애플리케이션을 빌드하는 개발자에게 다음과 같은 몇 가지 주요 이점을 제공합니다.

멀티 에이전트 시스템: 계층 구조에서 여러 전문 에이전트를 구성하여 모듈식의 확장 가능한 애플리케이션을 빌드합니다. 복잡한 조정 및 위임이 가능합니다.
다양한 도구 생태계: 사전 빌드된 도구 (검색, 코드 실행 등)를 사용하거나, 맞춤 함수를 만들거나, 서드 파티 에이전트 프레임워크 (LangChain, CrewAI)의 도구를 통합하거나, 다른 에이전트를 도구로 사용하는 등 다양한 기능을 에이전트에 제공합니다.
유연한 조정: 워크플로 에이전트 (SequentialAgent, ParallelAgent, LoopAgent)를 사용하여 예측 가능한 파이프라인을 위한 워크플로를 정의하거나 LLM 기반 동적 라우팅 (LlmAgent 전송)을 활용하여 적응형 동작을 구현합니다.
통합 개발자 환경: 강력한 CLI와 대화형 개발 UI를 사용하여 로컬에서 개발, 테스트, 디버그합니다. 이벤트, 상태, 에이전트 실행을 단계별로 검사합니다.
내장 평가: 최종 응답 품질과 단계별 실행 궤적을 사전 정의된 테스트 사례와 비교하여 평가함으로써 에이전트 성능을 체계적으로 평가합니다.
배포 준비: 에이전트를 컨테이너화하고 어디에나 배포하세요. 로컬에서 실행하거나, Vertex AI Agent Engine으로 확장하거나, Cloud Run 또는 Docker를 사용하여 맞춤 인프라에 통합할 수 있습니다.

다른 생성형 AI SDK나 에이전트 프레임워크를 사용하면 모델을 쿼리하고 도구를 사용하여 모델을 강화할 수도 있지만, 여러 모델 간의 동적 조율에는 상당한 작업이 필요합니다.

에이전트 개발 키트는 이러한 도구보다 높은 수준의 프레임워크를 제공하므로 복잡하지만 유지관리하기 쉬운 워크플로를 위해 여러 에이전트를 서로 쉽게 연결할 수 있습니다.

4. A2A 소개

Agent2Agent (A2A) 프로토콜은 다양한 프레임워크, 공급업체, 도메인의 자율 AI 에이전트 간에 원활하고 안전한 통신과 협업을 지원하도록 설계된 개방형 표준입니다.

범용 상호 운용성: A2A를 사용하면 에이전트가 기본 기술과 관계없이 함께 작동하여 진정한 멀티 에이전트 생태계를 조성할 수 있습니다. 즉, 서로 다른 플랫폼에서 서로 다른 회사에서 빌드한 에이전트가 통신하고 조정할 수 있습니다.
기능 검색: 에이전트는 ID, 지원되는 A2A 기능, 기술, 인증 요구사항을 설명하는 '에이전트 카드' (JSON 문서)를 사용하여 기능을 광고할 수 있습니다. 이를 통해 다른 에이전트가 특정 작업에 가장 적합한 에이전트를 검색하고 선택할 수 있습니다.
기본 보안: 보안은 핵심 원칙입니다. A2A는 HTTPS/TLS, JWT, OIDC, API 키와 같은 표준을 활용하여 안전한 상호작용을 보장하고 민감한 데이터를 보호하는 엔터프라이즈급 인증 및 승인 메커니즘을 통합합니다.
모달리티에 구애받지 않음: 이 프로토콜은 텍스트, 오디오, 동영상 스트리밍은 물론 대화형 양식과 삽입된 iframe 등 다양한 커뮤니케이션 모달리티를 지원합니다. 이러한 유연성을 통해 상담사는 작업과 사용자에게 가장 적합한 형식으로 정보를 교환할 수 있습니다.
구조화된 작업 관리: A2A는 작업 위임, 모니터링, 완료에 관한 명확한 프로토콜을 정의합니다. 관련 작업을 그룹화하고 고유한 작업 ID를 사용하여 여러 에이전트에서 작업을 관리할 수 있습니다. 작업은 정의된 수명 주기 (예: 제출됨, 작업 중, 완료됨)를 거쳐 전환될 수 있습니다.
불투명한 실행: 중요한 기능은 에이전트가 다른 에이전트에게 내부 추론 프로세스, 메모리 또는 특정 도구를 공개하지 않아도 된다는 것입니다. 호출 가능한 서비스만 노출하여 모듈성과 개인 정보 보호를 촉진합니다.
기존 표준 기반: A2A는 실시간 스트리밍을 위한 HTTP, 서버 전송 이벤트 (SSE), 구조화된 데이터 교환을 위한 JSON-RPC와 같은 기존 웹 기술을 활용하므로 기존 IT 인프라와 더 쉽게 통합할 수 있습니다.
비동기 통신: 이 프로토콜은 비동기 통신을 기본 고려사항으로 설계되어 유연한 작업 진행을 지원하고 연결이 지속적으로 유지되지 않는 경우에도 업데이트를 위한 푸시 알림을 사용 설정합니다.

5. 에이전트 아키텍처

이 실습에서는 사양에 따라 이미지를 생성하고 이미지를 평가한 후 사용자에게 표시하는 다중 에이전트 애플리케이션을 만듭니다.

시스템은 전체 프로세스를 오케스트레이션하는 image_scoring이라는 기본 에이전트로 구성됩니다. 이 기본 에이전트에는 image_generation_scoring_agent라는 하위 에이전트가 있으며, 이 하위 에이전트에는 더 구체적인 작업을 위한 자체 하위 에이전트가 있습니다. 이렇게 하면 기본 에이전트가 하위 에이전트에게 작업을 위임하는 계층적 관계가 생성됩니다. 그림 2: 전체 에이전트 흐름

모든 상담사 목록

image_scoring (기본 상담사):
목적: 전체 워크플로를 관리하는 루트 에이전트입니다. 종료 조건이 충족될 때까지 루프에서 image_generation_scoring_agent와 checker_agent를 반복적으로 실행합니다.
하위 에이전트:

image_generation_scoring_agent
checker_agent_instance

image_generation_scoring_agent (image_scoring의 하위 에이전트):
목적: 이 에이전트는 이미지를 생성하고 점수를 매기는 핵심 로직을 담당합니다. 이를 위해 세 개의 하위 에이전트 시퀀스를 실행합니다.
하위 에이전트:

image_generation_prompt_agent
image_generation_agent
scoring_images_prompt

checker_agent_instance (image_scoring의 하위 에이전트):
목적: 이 에이전트는 이미지 점수 매기기 프로세스를 계속해야 하는지 또는 종료해야 하는지 확인합니다. check_tool_condition 도구를 사용하여 종료 조건을 평가합니다.
image_generation_prompt_agent (image_generation_scoring_agent의 하위 에이전트):
목적: 이 에이전트는 이미지 생성을 위한 프롬프트 생성 전문가입니다. 입력 텍스트를 가져와 이미지 생성 모델에 적합한 상세한 프롬프트를 생성합니다.
image_generation_agent (image_generation_scoring_agent의 하위 에이전트):
목적: 이 에이전트는 Imagen 3를 사용하여 이미지를 만드는 데 능숙합니다. image_generation_prompt_agent의 프롬프트를 가져와 이미지를 생성합니다.
scoring_images_prompt (image_generation_scoring_agent의 하위 에이전트):
목적: 이 에이전트는 다양한 기준에 따라 이미지를 평가하고 점수를 매기는 전문가입니다. 생성된 이미지를 가져와 점수를 할당합니다.

상담사가 사용하는 도구

check_tool_condition:
설명: 이 도구는 루프 종료 조건이 충족되었는지 또는 최대 반복 횟수에 도달했는지 확인합니다. 이 중 하나라도 참이면 루프가 중지됩니다.
사용자: checker_agent_instance
generate_images:
설명: 이 도구는 Imagen 3 모델을 사용하여 이미지를 생성합니다. 생성된 이미지를 Google Cloud Storage 버킷에 저장할 수도 있습니다.
사용 주체: image_generation_agent
get_policy:
설명: 이 도구는 JSON 파일에서 정책을 가져옵니다. 이 정책은 image_generation_prompt_agent가 이미지 생성 프롬프트를 만드는 데 사용되고 scoring_images_prompt가 이미지를 평가하는 데 사용됩니다.
사용자: image_generation_prompt_agent, scoring_images_prompt
get_image:
설명: 이 도구는 생성된 이미지 아티팩트를 로드하여 점수를 매길 수 있도록 합니다.
사용자: scoring_images_prompt
set_score:
설명: 이 도구는 세션 상태에서 생성된 이미지의 총 점수를 설정합니다.
사용자: scoring_images_prompt

6. 작업 1. ADK 설치 및 환경 설정

이 실습에서는 Cloud Shell을 사용하여 작업을 수행합니다.

Vertex AI 권장 API 사용 설정

Google Cloud 콘솔 상단에서 Vertex AI를 검색하여 이동합니다.
모든 권장 API 사용 설정을 클릭합니다.

Cloud Shell 편집기 탭 준비

Google Cloud 콘솔 창을 선택한 상태에서 키보드의 G 키를 누른 다음 S 키를 눌러 Cloud Shell을 엽니다. 또는 Google Cloud 콘솔의 오른쪽 상단에 있는 Cloud Shell 버튼 을 클릭할 수도 있습니다.
계속을 클릭합니다.
Cloud Shell을 승인하라는 메시지가 표시되면 승인을 클릭합니다.
Cloud Shell 창의 오른쪽 상단에서 새 창에서 열기 버튼 을 클릭합니다.
창 상단에 있는 편집기 열기 연필 아이콘 ( )을 클릭하여 파일을 확인합니다.
왼쪽 탐색 메뉴 상단에서 탐색기 아이콘 을 클릭하여 파일 탐색기를 엽니다.
폴더 열기 버튼을 클릭합니다.
이 실습의 나머지 부분에서는 Cloud Shell 편집기 및 Cloud Shell 터미널이 있는 이 창에서 IDE로 작업할 수 있습니다.

이 실습의 ADK 및 코드 샘플 다운로드 및 설치

다음 명령어를 실행하여 GitHub에서 필요한 소스를 클론하고 필요한 라이브러리를 설치합니다.

#create the project directory
mkdir imagescoring
cd imagescoring
#clone the code in the local directory
git clone https://github.com/haren-bh/multiagenthandson.git

#Create the virtual environment
python3 -m venv pythonenv
source pythonenv/bin/activate

#install google-adk and a2a sdk
python3 -m pip install google-adk==1.8.0
python3 -m pip install a2a-sdk==0.2.16

poetry를 사용하여 추가 요구사항을 설치합니다.

cd multiagenthandson #go to the application directory
pip install poetry poetry-plugin-export
poetry install --with deployment

클라우드 스토리지 버킷이 없으면 Google Cloud Storage에서 새 버킷을 만듭니다. gsutil 명령어를 사용하여 버킷을 만들 수도 있습니다.

gsutil mb gs://YOUR-UNIQUE-BUCKETNAME

편집기에서 보기 -> 숨김 파일 전환으로 이동합니다. image_scoring 폴더에서 다음 콘텐츠로 .env 파일을 만듭니다. 프로젝트 이름, 클라우드 스토리지 버킷과 같은 필수 세부정보를 추가합니다.

GOOGLE_GENAI_USE_VERTEXAI=1 #1 if VERTEXAI has to be used. Can be 0 if API_KEY is specified
GOOGLE_CLOUD_PROJECT=YOUR CLOUD PROJECT NAME
GOOGLE_CLOUD_LOCATION=us-central1
GOOGLE_CLOUD_STORAGE_BUCKET=YOUR BUCKET NAME  # Only required for deployment on Agent Engine
GCS_BUCKET_NAME=YOUR BUCKET NAME #Bucket for storing generated images.
SCORE_THRESHOLD=40 # Min threshold for image_score. Max Score is 50 , hence should be less than 50. 
#If the computed score is higher then loop will terminate
#MAX_ITERATIONS=5 #Max iterations for evaluating the image_score before terminating the loop.
IMAGEN_MODEL="imagen-3.0-generate-002" 
GENAI_MODEL="gemini-2.5-flash"
#AGENT_ENGINE_ID=<AGENT_ENGINE_ID> #The Agent Engine ID obtained after deploying to the agent engine.

소스 코드에서 에이전트 구조를 살펴봅니다(agent.py부터 시작). 이 에이전트에는 다른 에이전트에 연결되는 루트 에이전트가 포함되어 있습니다.
터미널에서 최상위 디렉터리 multiagenthandson으로 돌아가 다음 명령어를 실행하여 에이전트를 로컬에서 실행합니다.

# Run the following command to run agents locally
export GCS_BUCKET_NAME=your gcs bucket name
adk web

그림 1

터미널에 표시된 http:// URL을 Ctrl+클릭 (MacOS의 경우 CMD+클릭)하여 ADK의 브라우저 기반 GUI 클라이언트를 엽니다. 그림 2와 같이 표시됩니다.

이미지를 생성해 보겠습니다. 다음 프롬프트 또는 직접 만든 프롬프트를 사용해 보세요.
일몰 시 평화로운 산 풍경
자전거를 타는 고양이

그림 2

7. 작업 2. Agent Engine에 배포

이제 에이전트를 에이전트 엔진에 배포합니다. Agent Engine은 GCP에서 에이전트를 배포하기 위한 완전 관리형 서비스입니다. Agent Engine은 ADK와 호환되므로 ADK로 빌드된 에이전트를 Agent Engine에 배포할 수 있습니다.

몇 가지 환경 변수를 정의합니다.

export GOOGLE_CLOUD_LOCATION='us-central1'
export GOOGLE_CLOUD_PROJECT='your project id'

poetry를 사용하여 requirements.txt 파일을 만듭니다. Poetry는 pyproject.toml을 사용하여 requirements.txt 파일을 만듭니다. 명령어를 실행한 후 requirements.txt 파일이 생성되었는지 확인합니다.

# Go to the parent folder containing pyproject.toml file
# install poetry-plugin-export
pip install poetry-plugin-export

#Create requirements.txt file
poetry export -f requirements.txt --output requirements.txt --without-hashes

패키지를 만듭니다. 앱을 .whl Python 패키지로 번들링해야 합니다. 이를 위해 poetry를 사용합니다. 명령어를 실행한 후 dist 폴더가 생성되고 .whl 파일이 포함되어 있는지 확인합니다.

# Go to the parent folder containing pyproject.toml file
#Create python package, to create whl file
poetry build

이제 배포 스크립트를 준비합니다. 배포 스크립트는 이미지 점수 매기기 에이전트 또는 에이전트 엔진 서비스를 배포합니다. image_scoring 폴더 내 deploy.py의 콘텐츠를 아래와 같이 변경하세요.

# Change the content of the following. Look for #change this comment
import vertexai
from .agent import root_agent
import os
import glob # To easily find the wheel file

PROJECT_ID = "YOUR PROJECT ID" #change this your project
LOCATION = "us-central1" #change this
STAGING_BUCKET = "gs://YOUR BUCKET " #change this to your bucket

from vertexai import agent_engines

vertexai.init(
   project=PROJECT_ID,
   location=LOCATION,
   staging_bucket=STAGING_BUCKET,
)

remote_app = agent_engines.create(
   agent_engine=root_agent,
   requirements=open(os.path.join(os.getcwd(), "requirements.txt")).readlines()+["./dist/image_scoring-0.1.0-py3-none-any.whl"],#change this to your local location
   extra_packages=[
       "./dist/image_scoring-0.1.0-py3-none-any.whl", # change this to your location
   ]
)

print(remote_app.resource_name)

이제 배포 스크립트를 실행할 수 있습니다.

#run deploy script from the parent folder containing deploy.py
python3 -m image_scoring.deploy

배포 후에는 아래와 같이 표시됩니다.

그림 3

이제 배포된 에이전트를 테스트해 보겠습니다. 원격으로 배포된 에이전트 엔진을 테스트하려면 먼저 터미널의 배포 출력에서 에이전트 위치를 복사하세요. projects/85469421903/locations/us-central1/reasoningEngines/7369674597261639680과 같이 표시됩니다 .
testclient 폴더로 이동하여 remote_test.py 파일을 열고 다음 줄을 수정합니다.

PROJECT_ID = "" #change this
LOCATION = "" #change this
STAGING_BUCKET = "" #change this

#replace the id with your own.
reasoning_engine_id="your agent engine id"

#You can replace this with your own prompt
image_prompt="A cat riding a bicycle"

#execute remote_test.py
python3 remote_test.py

8. 작업 3. A2A 에이전트 만들기

이 단계에서는 이전 단계에서 만든 에이전트를 기반으로 간단한 A2A 에이전트를 만듭니다. 기존 ADK 에이전트는 A2A 프로토콜에 따라 게시할 수 있습니다. 이 단계에서 학습할 주요 사항은 다음과 같습니다.

A2A 프로토콜의 기본사항을 알아봅니다.
ADK와 A2A 프로토콜이 서로 어떻게 작동하는지 알아봅니다.
A2A 프로토콜과 상호작용하는 방법을 알아봅니다.

이 실습에서는 image_scoring_adk_a2a_server 폴더의 코드를 사용합니다. 작업을 시작하기 전에 디렉터리를 이 폴더로 변경하세요.

A2A 에이전트 카드 만들기

A2A 프로토콜에는 에이전트 기능, 에이전트 사용 가이드 등 에이전트에 관한 모든 정보가 포함된 에이전트 카드가 필요합니다. A2A 에이전트가 배포되면 '.well-known/agent-card.json' 링크를 사용하여 에이전트 카드를 볼 수 있습니다. 클라이언트는 이 정보를 참고하여 에이전트에 요청을 보낼 수 있습니다.

remote_a2a/image_scoring 폴더에 다음 콘텐츠가 포함된 agents.json이 있는지 확인합니다.

{
 "name": "image_scoring",
 "description": "Agent that generates images based on user prompts and scores their adherence to the prompt.",
 "url": "http://localhost:8001/a2a/image_scoring",
 "version": "1.0.0",
 "defaultInputModes": ["text/plain"],
 "defaultOutputModes": ["image/png", "text/plain"],
 "capabilities": {
   "streaming": true,
   "functions": true
 },
 "skills": [
   {
     "id": "generate_and_score_image",
     "name": "Generate and Score Image",
     "description": "Generates an image from a given text prompt and then evaluates how well the generated image adheres to the original prompt, providing a score.",
     "tags": ["image generation", "image scoring", "evaluation", "AI art"],
     "examples": [
       "Generate an image of a futuristic city at sunset",
       "Create an image of a cat playing a piano",
       "Show me an image of a serene forest with a hidden waterfall"
     ]
   }
 ]
}

A2A 에이전트 만들기

루트 폴더 image_scoring_adk_a2a_server 내에 a2a 에이전트의 진입점인 a2a_agent.py 파일이 있는지 확인합니다. 다음 콘텐츠가 있어야 합니다.

from google.adk.agents.remote_a2a_agent import RemoteA2aAgent

root_agent = RemoteA2aAgent(
   name="image_scoring",
   description="Agent to give interesting facts.",
   agent_card="http://localhost:8001/a2a/image_scoring/.well-known/agent.json",
  
   # Optional configurations
   timeout=300.0,          # HTTP timeout (seconds)
   httpx_client=None,      # Custom HTTP client
)

A2A 에이전트 실행

이제 에이전트를 실행할 준비가 되었습니다. 에이전트를 실행하려면 최상위 폴더 image_scoring_adk_a2a_server 내에서 다음 명령어를 실행하세요.

#set some environmental variables
export GOOGLE_CLOUD_PROJECT=datapipeline-372305
export GOOGLE_CLOUD_LOCATION=us-central1
export GCS_BUCKET_NAME=haren-genai-bucket

#following command runs the ADK agent as a2a agent
adk api_server --a2a --port 8001 remote_a2a

A2A 에이전트 테스트

에이전트가 실행되면 이제 에이전트를 테스트할 수 있습니다. 먼저 상담사 카드를 확인해 보겠습니다.

#Execute the following 
curl http://localhost:8001/a2a/image_scoring/.well-known/agent.json

위의 코드를 실행하면 A2A 에이전트의 에이전트 카드가 표시됩니다. 이는 이전 단계에서 만든 agent.json의 콘텐츠입니다.

이제 에이전트에게 요청을 보내겠습니다. curl을 사용하여 에이전트에 요청을 보낼 수 있습니다.

curl -X POST   http://localhost:8001/a2a/image_scoring   -H 'Content-Type: application/json'   -d '{
    "id": "uuid-123",
    "params": {
      "message": {
        "messageId": "msg-456",
        "parts": [{"text": "Create an image of a cat"}],
        "role": "user"
      }
    }
  }'

위 요청에서 '고양이 이미지 만들기' 줄을 변경하여 프롬프트를 변경할 수 있습니다. 명령어를 실행하면 지정된 Google Cloud Storage에서 출력 이미지를 확인할 수 있습니다.

9. 삭제

이제 방금 만든 항목을 정리해 보겠습니다.

방금 만든 Agent Engine 서버를 삭제합니다. Google Cloud 콘솔의 검색창에 Vertex AI를 입력하여 Vertex AI로 이동합니다. 왼쪽의 에이전트 엔진을 클릭합니다.삭제를 클릭하여 에이전트를 삭제할 수 있습니다.

그림 4

Cloud Shell에서 파일 삭제

#Execute the following to delete the files
rm -R imagescoring

버킷을 삭제합니다. GCP 콘솔->Cloud Storage로 이동하여 버킷을 선택하고 삭제하면 됩니다.