ADK로 A2A 에이전트 구현하기: 완전한 개발 가이드

Cheng Zhang·2025년 7월 15일
A2AADK

A2A

목록 보기
10/20
post-thumbnail

목차

  1. ADK와 A2A 프로토콜 개요
  2. 환경 설정 및 의존성 설치
  3. 프로젝트 구조 설계
  4. A2A 서버 측 에이전트 개발
  5. A2A 클라이언트 측 에이전트 개발
  6. 에이전트 구성 및 메타데이터
  7. A2A 서버 시작 및 테스트
  8. 웹 UI 통합 테스트
  9. A2A 통신 플로우 상세 설명

ADK와 A2A 프로토콜 개요

ADK와 A2A란 무엇인가?

ADK(Agent Development Kit)는 Google에서 개발한 지능형 에이전트 개발 프레임워크이며, A2A(Agent2Agent Protocol)는 표준화된 에이전트 간 통신 프로토콜입니다. ADK 프레임워크는 A2A 에이전트에 대한 완전한 지원을 내장하고 있으며, RemoteA2aAgent와 같은 핵심 구성 요소를 제공하여 개발자가 다음을 수행할 수 있도록 합니다:

  • 🔗 원활한 연결: 분산 에이전트 간 표준화된 통신 구현
  • 🚀 신속한 개발: 간단한 API를 사용하여 복잡한 에이전트 시스템을 빠르게 구축
  • 🔄 프로토콜 표준화: A2A 프로토콜 사양을 따라 상호 운용성 보장
  • 🎯 지능형 라우팅: 메시지 라우팅 및 형식 변환 자동 처리
  • 📊 관찰 가능성: 내장된 로깅 및 모니터링 기능

중요 참고사항: ADK는 개발 프레임워크이고, A2A는 통신 프로토콜입니다. ADK는 A2A 프로토콜의 구현을 포함하고 있어 개발자가 Agent2Agent 통신을 지원하는 지능형 에이전트 시스템을 쉽게 구축할 수 있습니다. 이 가이드는 ADK 프레임워크 내에서 A2A 기능을 사용하는 방법을 보여줍니다.

ADK의 A2A 기능 핵심 장점

  1. 분산 아키텍처: 다양한 서버와 환경에 에이전트 배포를 지원하며, A2A 프로토콜을 통해 통신
  2. 표준화된 프로토콜: A2A 통신 프로토콜 사양을 따라 크로스 플랫폼 호환성 보장
  3. 즉시 사용 가능: ADK는 A2A 지원이 내장된 완전한 CLI 도구와 웹 UI 제공
  4. 높은 확장성: 사용자 정의 도구와 복잡한 비즈니스 로직을 지원하며, A2A 생태계와 호환
  5. 프로덕션 준비: 엔터프라이즈급 보안 및 신뢰성 보장

환경 설정 및 의존성 설치

시스템 요구사항

  • Python: 3.10 이상
  • 운영 체제: Linux, macOS 또는 Windows
  • API 키: Gemini API 키 (LLM 기능용)

1단계: 프로젝트 디렉토리 생성

# 프로젝트 루트 디렉토리 생성
mkdir adk-a2a-demo
cd adk-a2a-demo

# 가상 환경 생성
python -m venv .venv

# 가상 환경 활성화
# Linux/macOS:
source .venv/bin/activate
# Windows:
# .venv\Scripts\activate

2단계: ADK 의존성 설치 (A2A 지원 포함)

# ADK 핵심 패키지 설치 (A2A 프로토콜 지원 포함)
pip install google-adk[a2a]>=1.6.1

# 설치 확인
adk --version

3단계: 환경 변수 구성

# .env 파일 생성
echo "GOOGLE_API_KEY=your_gemini_api_key_here" > .env

# 환경 변수 설정 (임시)
export GOOGLE_API_KEY="your_gemini_api_key_here"

프로젝트 구조 설계

ADK 기반 권장 A2A 프로젝트 구조

adk-a2a-demo/
├── .env                    # 환경 변수 구성
├── requirements.txt        # Python 의존성
├── __init__.py            # 메인 프로젝트 초기화
├── agent.py               # A2A 클라이언트 에이전트 (RemoteA2aAgent)
├── remote_a2a/            # A2A 서버 측 에이전트 디렉토리
│   └── facts_agent/       # 특정 에이전트 구현
│       ├── __init__.py    # 에이전트 패키지 초기화
│       ├── agent.py       # 에이전트 핵심 로직
│       └── agent.json     # A2A 에이전트 메타데이터 구성
└── README.md              # 프로젝트 문서

기본 프로젝트 구조 생성

# 필요한 디렉토리 및 파일 생성
mkdir -p remote_a2a/facts_agent
touch __init__.py agent.py
touch remote_a2a/facts_agent/__init__.py
touch remote_a2a/facts_agent/agent.py
touch remote_a2a/facts_agent/agent.json
touch requirements.txt

A2A 서버 측 에이전트 개발

1단계: 서버 측 에이전트 구현 생성

서버 측 에이전트는 실제로 비즈니스 로직을 실행하는 핵심 구성 요소입니다. remote_a2a/facts_agent/agent.py에서 구현:

# remote_a2a/facts_agent/agent.py

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

# 서버 측 에이전트 정의
root_agent = Agent(
    # 에이전트 고유 식별자
    name="facts_agent",
    
    # 사용할 대형 언어 모델
    model="gemini-2.0-flash",
    
    # 에이전트 기능 설명
    description="흥미로운 사실을 제공하는 에이전트입니다.",
    
    # 에이전트 행동 지침
    instruction=(
        "당신은 흥미로운 사실을 제공할 수 있는 도움이 되는 에이전트입니다. "
        "Google 검색을 사용하여 정확하고 최신 정보를 찾으세요. "
        "항상 사실에 대한 출처를 제공하세요."
    ),
    
    # 사용 가능한 도구 목록
    tools=[google_search],
)

2단계: 에이전트 패키지 초기화 구성

remote_a2a/facts_agent/__init__.py에서:

# remote_a2a/facts_agent/__init__.py

# ADK가 발견할 수 있도록 에이전트 구현 가져오기
from . import agent

3단계: 서버 측 에이전트 핵심 기능 분석

# 에이전트의 핵심 구성 요소 설명

# 1. 이름 (name)
# - 고유해야 하며, A2A 네트워크에서 에이전트를 식별하는 데 사용
# - 설명적인 이름 사용 권장

# 2. 모델 (model)
# - 사용할 대형 언어 모델 지정
# - Gemini 시리즈 모델 지원

# 3. 설명 (description)
# - 에이전트 기능에 대한 간단한 설명
# - 에이전트 발견 중에 다른 에이전트에게 표시됨

# 4. 지침 (instruction)
# - 상세한 행동 지침
# - 에이전트 성격 및 응답 스타일 정의

# 5. 도구 (tools)
# - 에이전트가 호출할 수 있는 외부 도구
# - 검색, 계산, API 호출 등

A2A 클라이언트 측 에이전트 개발

1단계: 클라이언트 측 에이전트 생성

클라이언트 측 에이전트는 RemoteA2aAgent를 사용하여 원격 서비스에 연결합니다. agent.py에서 구현:

# agent.py

from google.adk.agents.remote_a2a_agent import RemoteA2aAgent

# 원격 A2A 클라이언트 에이전트 정의
root_agent = RemoteA2aAgent(
    # 클라이언트 에이전트 이름
    name="facts_agent",
    
    # 기능 설명
    description="흥미로운 사실을 제공하는 에이전트입니다.",
    
    # 원격 에이전트 카드 URL
    agent_card="http://localhost:8001/a2a/facts_agent/.well-known/agent.json",
)

2단계: RemoteA2aAgent 상세 구성

# 고급 구성 예제
root_agent = RemoteA2aAgent(
    name="facts_agent",
    description="흥미로운 사실을 제공하는 에이전트입니다.",
    agent_card="http://localhost:8001/a2a/facts_agent/.well-known/agent.json",
    
    # 선택적 구성
    timeout=300.0,          # HTTP 타임아웃 (초)
    httpx_client=None,      # 사용자 정의 HTTP 클라이언트
)

3단계: 클라이언트 측 에이전트 작동 원리

  1. 에이전트 발견: agent_card URL을 통해 원격 에이전트 정보 획득
  2. 연결 설정: 원격 A2A 서버에 HTTP 연결 생성
  3. 메시지 변환: 로컬 이벤트를 A2A 프로토콜 메시지로 변환
  4. 원격 호출: 원격 에이전트에 요청 전송
  5. 응답 처리: 원격 에이전트 응답 수신 및 변환

에이전트 구성 및 메타데이터

1단계: 에이전트 구성 파일 생성

remote_a2a/facts_agent/agent.json에서 에이전트 메타데이터 정의:

{
  "name": "facts_agent",
  "description": "흥미로운 사실을 제공하는 에이전트입니다.",
  "url": "http://localhost:8001/a2a/facts_agent",
  "version": "1.0.0",
  "defaultInputModes": ["text/plain"],
  "defaultOutputModes": ["text/plain"],
  "capabilities": {
    "streaming": true,
    "functions": true
  },
  "skills": [
    {
      "id": "give_facts",
      "name": "흥미로운 사실",
      "description": "Google 검색을 사용하여 다양한 주제에 대한 흥미로운 사실을 제공합니다.",
      "tags": ["정보", "사실", "지식", "검색", "구글"],
      "examples": [
        "뉴욕시에 대한 흥미로운 사실을 알려주세요.",
        "양자 물리학에 대한 매혹적인 사실을 말해주세요.",
        "해양 생물에 대한 특이한 사실은 무엇인가요?"
      ]
    }
  ]
}

2단계: 구성 필드 설명

{
  // 기본 정보
  "name": "에이전트 고유 식별자",
  "description": "에이전트 기능에 대한 간단한 설명",
  "url": "A2A 서비스 엔드포인트 URL",
  "version": "버전 번호 (시맨틱 버전 관리)",
  
  // 입력/출력 모드
  "defaultInputModes": ["지원되는 입력 형식"],
  "defaultOutputModes": ["지원되는 출력 형식"],
  
  // 에이전트 기능
  "capabilities": {
    "streaming": "스트리밍 응답 지원 여부",
    "functions": "함수 호출 지원 여부"
  },
  
  // 스킬 정의
  "skills": [
    {
      "id": "스킬 고유 식별자",
      "name": "스킬 표시 이름",
      "description": "상세한 스킬 설명",
      "tags": ["태그1", "태그2"],
      "examples": ["사용 예제 1", "사용 예제 2"]
    }
  ]
}

3단계: 의존성 파일 생성

requirements.txt에서:

google-adk[a2a]>=1.6.1

__init__.py에서:

# 프로젝트 초기화 파일
from . import agent

A2A 서버 시작 및 테스트

1단계: A2A 서버 시작

# 프로젝트 루트 디렉토리에 있고 가상 환경이 활성화되어 있는지 확인
source .venv/bin/activate

# A2A 서버 시작
adk api_server --a2a --port 8001 remote_a2a

# 예상 출력:
# INFO:     Uvicorn running on http://127.0.0.1:8001 (Press CTRL+C to quit)
# INFO:     A2A endpoints enabled for agents: facts_agent

2단계: A2A 엔드포인트 확인

# 에이전트 발견 엔드포인트 테스트
curl http://localhost:8001/a2a/facts_agent/.well-known/agent.json

# 에이전트 구성 JSON 반환 예상

3단계: A2A 서버 아키텍처 분석

A2A 서버가 시작된 후 다음 엔드포인트를 생성합니다:

  1. 에이전트 발견 엔드포인트: /.well-known/agent.json

    • 에이전트 메타데이터 및 기능 정보 제공
    • 자동 에이전트 발견 및 구성에 사용

  2. 메시지 처리 엔드포인트: /a2a/{agent_name}

    • 다른 에이전트로부터 메시지 수신
    • A2A 프로토콜 요청 처리

  3. 상태 확인 엔드포인트: /health

    • 서버 상태 모니터링
    • 로드 밸런서 상태 확인

웹 UI 통합 테스트

1단계: ADK 웹 서버 시작

새 터미널 창에서:

# 가상 환경 활성화
source .venv/bin/activate

# 웹 UI 서버 시작
adk web .

# 예상 출력:
# INFO:     Uvicorn running on http://127.0.0.1:8000 (Press CTRL+C to quit)
# INFO:     Available agents: facts_agent

2단계: 웹 UI 테스트 프로세스

  1. 웹 UI 접근: 브라우저에서 http://localhost:8000 열기

  2. 에이전트 선택: 드롭다운 메뉴에서 facts_agent 선택

  3. 대화 테스트: 테스트 메시지 입력, 예를 들어:

    "인공지능에 대한 흥미로운 사실을 알려주세요"

  4. 응답 관찰: 에이전트가 올바르게 응답하고 Google 검색 도구를 사용하는지 확인

3단계: 테스트 케이스 예제

# 테스트 케이스 1: 기본 사실 질의
입력: 만리장성에 대한 흥미로운 사실은 무엇인가요?
예상: 검색 출처를 포함한 만리장성에 대한 흥미로운 사실 반환

# 테스트 케이스 2: 과학 지식 질의
입력: 블랙홀에 대한 매혹적인 사실을 말해주세요.
예상: 블랙홀에 대한 과학적 사실 반환

# 테스트 케이스 3: 시사 질의
입력: 우주 탐사의 최근 발견은 무엇인가요?
예상: 최신 우주 탐사 발견 반환

A2A 통신 플로우 상세 설명

완전한 A2A 통신 시퀀스 다이어그램

sequenceDiagram
    participant User as 사용자
    participant WebUI as ADK 웹 UI<br/>(localhost:8000)
    participant Client as 클라이언트 에이전트<br/>(RemoteA2aAgent)
    participant A2AServer as A2A 서버<br/>(localhost:8001)
    participant Agent as 서버 에이전트<br/>(facts_agent)
    participant LLM as Gemini LLM
    participant Search as Google 검색

    User->>WebUI: 1. 질의 메시지 입력
    WebUI->>Client: 2. 클라이언트 에이전트 호출
    
    Note over Client: 3. 에이전트 초기화 확인
    Client->>A2AServer: 4. GET /.well-known/agent.json
    A2AServer-->>Client: 5. 에이전트 구성 반환
    
    Note over Client: 6. A2A 메시지 구축
    Client->>A2AServer: 7. POST /a2a/facts_agent<br/>A2A 메시지 전송
    
    A2AServer->>Agent: 8. 내부 이벤트로 변환
    Agent->>LLM: 9. 프롬프트 전송
    LLM-->>Agent: 10. 응답 반환 (도구 호출 포함)
    
    Agent->>Search: 11. Google 검색 실행
    Search-->>Agent: 12. 검색 결과 반환
    
    Agent->>LLM: 13. 검색 결과 통합
    LLM-->>Agent: 14. 최종 응답 생성
    
    Agent-->>A2AServer: 15. 처리 결과 반환
    A2AServer-->>Client: 16. A2A 응답 반환
    
    Note over Client: 17. 내부 이벤트로 변환
    Client-->>WebUI: 18. 응답 반환
    WebUI-->>User: 19. 최종 결과 표시

주요 통신 단계 분석

1. 에이전트 발견 단계 (4-5단계)

GET http://localhost:8001/a2a/facts_agent/.well-known/agent.json

응답:
{
  "name": "facts_agent",
  "url": "http://localhost:8001/a2a/facts_agent",
  "skills": [...]
}

2. 메시지 전송 단계 (7단계)

POST http://localhost:8001/a2a/facts_agent
Content-Type: application/json

{
  "id": "uuid-123",
  "params": {
    "message": {
      "messageId": "msg-456",
      "parts": [{"text": "AI에 대한 사실을 알려주세요"}],
      "role": "user"
    }
  }
}

3. 응답 반환 단계 (16단계)

HTTP/1.1 200 OK
Content-Type: application/json

{
  "result": {
    "messageId": "response-789",
    "parts": [{"text": "다음은 흥미로운 AI 사실입니다..."}],
    "role": "agent"
  }
}

요약

이 가이드를 통해 ADK 프레임워크를 사용하여 A2A 프로토콜을 구현하여 완전한 에이전트 간 통신 시스템을 구축하는 방법을 배웠습니다. 주요 학습 내용은 다음과 같습니다:

🎯 핵심 기술

  • ✅ ADK A2A 환경 설정: 처음부터 개발 환경 구성
  • ✅ A2A 서버 측 에이전트 개발: ADK를 사용하여 실제 기능을 가진 지능형 에이전트 생성
  • ✅ A2A 클라이언트 측 에이전트 개발: RemoteA2aAgent를 통한 원격 에이전트 연결 구현
  • ✅ A2A 프로토콜 이해: Agent2Agent 통신 프로토콜의 깊은 숙달
  • ✅ ADK 웹 UI 테스트: ADK 제공 웹 UI를 사용한 엔드투엔드 테스트

🚀 기술적 장점

  • 표준화: A2A 프로토콜 기반 표준화된 에이전트 통신
  • 분산: ADK는 서버 간 A2A 에이전트 배포 지원
  • 확장 가능: 새로운 기능 추가 및 A2A 생태계와의 통합 용이
  • 프로덕션 준비: 엔터프라이즈급 안정성 및 보안

🔮 다음 단계

  • 더 많은 ADK 도구 및 A2A 통합 옵션 탐색
  • 다중 A2A 에이전트 협업 시스템 구축
  • 사용자 정의 A2A 프로토콜 확장 구현
  • ADK A2A 솔루션을 프로덕션 환경에 배포

ADK의 A2A 구현은 차세대 지능형 에이전트 시스템 구축을 위한 강력한 기반을 제공하여 에이전트 협업을 간단하고 효율적으로 만듭니다. ADK A2A 개발 여정을 시작하세요!

참고 자료

키워드: A2A ADK, Agent Development Kit, A2A 프로토콜, 에이전트 개발, 지능형 에이전트 통신, Google ADK, 에이전트 프로토콜, 분산 에이전트 시스템, RemoteA2aAgent, Gemini API

profile
Cheng Zhang
독립 개발자
이전 포스트

A2A ADK 경비 상환 에이전트

다음 포스트

A2A 프로토콜 사양 (Python)

0개의 댓글