A2A Protocol

2025 Complete Guide: Agent2Agent (A2A) Protocol Advanced Features Deep Dive (Part 2)

deutschEnglishfrançaisहिंदी日本語한국어nederlands中文
MILO•
Share
2025 Complete Guide: Agent2Agent (A2A) Protocol Advanced Features Deep Dive (Part 2)

시리즈 참고: 이 글은 완전한 A2A 프로토콜 가이드의 파트 2로, 스트리밍 작업, 비동기 처리, 확장 메커니즘, 작업 생명주기 관리에 중점을 둡니다. 파트 1은 2025 완전 가이드: Agent2Agent (A2A) 프로토콜 - AI 에이전트 협업의 새로운 표준을 참조하세요.

🎯 핵심 포인트 (TL;DR)

  • 스트리밍 처리: A2A는 실시간 데이터 스트림 전송 및 증분 결과 처리를 위한 Server-Sent Events (SSE)를 지원합니다
  • 비동기 작업: 푸시 알림 메커니즘은 장기 실행 작업을 지원하며, 모바일 및 서버리스 시나리오에 적합합니다
  • 확장 시스템: 유연한 확장 메커니즘으로 사용자 정의 프로토콜 동작을 허용하며, 데이터 확장, 메서드 확장, 프로필 확장을 지원합니다
  • 작업 관리: 작업 추적, 상태 업데이트, 아티팩트 관리를 지원하는 완전한 작업 생명주기 관리

목차

  1. 스트리밍 작업 & Server-Sent Events
  2. 비동기 작업 & 푸시 알림
  3. 확장 메커니즘 심화 분석
  4. 작업 생명주기 관리
  5. 보안 고려사항
  6. 모범 사례
  7. 자주 묻는 질문

스트리밍 작업 & Server-Sent Events {#streaming-operations}

스트리밍 처리란 무엇인가?

A2A 프로토콜의 스트리밍 처리 메커니즘은 긴 실행 시간이 필요하거나, 증분 결과를 생성하거나, 실시간 피드백이 필요한 AI 작업을 처리하도록 특별히 설계되었습니다. Server-Sent Events (SSE) 기술을 통해 클라이언트는 실시간 작업 진행 업데이트와 부분 결과를 받을 수 있습니다.

스트리밍 처리의 핵심 기능

기능 설명 사용 사례
실시간 업데이트 SSE를 통한 작업 상태 변경 푸시 긴 문서 생성, 미디어 스트림 처리
증분 결과 대용량 아티팩트의 청크 전송 대용량 파일 처리, 실시간 분석
연결 관리 재연결 및 상태 복구 지원 불안정한 네트워크 환경
이벤트 타입 다양한 업데이트 요구를 위한 여러 이벤트 타입 상태 업데이트, 아티팩트 업데이트

스트리밍 처리 워크플로우

graph TD
    A[클라이언트가 message/stream 요청 시작] --> B[서버가 스트리밍 지원 확인]
    B --> C{스트리밍 지원?}
    C -->|예| D[SSE 연결 설정]
    C -->|아니오| E[오류 응답 반환]
    D --> F[작업 처리 시작]
    F --> G[상태 업데이트 이벤트 전송]
    G --> H[아티팩트 업데이트 이벤트 전송]
    H --> I{작업 완료?}
    I -->|아니오| G
    I -->|예| J[final: true 이벤트 전송]
    J --> K[SSE 연결 종료]

주요 구현 포인트

1. 서버 기능 선언

{
  "capabilities": {
    "streaming": true
  }
}

2. 이벤트 구조

A2A 스트리밍 처리는 세 가지 주요 이벤트 타입을 지원합니다:

  • Task Events: 처리 중인 작업 상태 단위를 나타냄
  • TaskStatusUpdateEvent: 작업 생명주기 상태 변경을 전달
  • TaskArtifactUpdateEvent: 새로 생성되거나 업데이트된 아티팩트를 전달

💡 프로 팁 각 SSE 이벤트의 data 필드에는 완전한 JSON-RPC 2.0 응답 객체가 포함되어 표준 프로토콜과의 호환성을 보장합니다.

3. 재연결 메커니즘

{
  "method": "tasks/resubscribe",
  "params": {
    "taskId": "task-123"
  }
}

적용 가능한 시나리오

✅ 스트리밍 처리 권장 시나리오:

  • 실시간 진행 모니터링이 필요한 장기 실행 작업
  • 대용량 결과의 증분 수신
  • 즉각적인 피드백이 필요한 대화형 대화
  • 낮은 지연 시간 업데이트가 필요한 애플리케이션

비동기 작업 & 푸시 알림 {#async-operations}

푸시 알림 메커니즘 개요

극도로 장기 실행되는 작업(분, 시간, 심지어 일)이나 지속적인 연결을 유지할 수 없는 클라이언트(모바일 앱, 서버리스 함수 등)의 경우, A2A는 Webhook 기반 푸시 알림 메커니즘을 제공합니다.

푸시 알림 구성

PushNotificationConfig 구조

{
  "url": "https://client.example.com/webhook",
  "token": "client-generated-secret-token",
  "authentication": {
    "schemes": ["Bearer", "HMAC"],
    "details": {
      "issuer": "a2a-server.example.com",
      "audience": "client-webhook"
    }
  }
}

구성 방법 비교

구성 방법 타이밍 사용 사례
요청 내 구성 message/send 또는 message/stream 중 일회성 작업 알림
독립 구성 tasks/pushNotificationConfig/set 사용 기존 작업에 알림 추가

푸시 알림 워크플로우

graph TD
    A[클라이언트가 푸시 알림 구성] --> B[서버가 Webhook URL 검증]
    B --> C[작업 실행 시작]
    C --> D[작업 상태가 중요한 변경 발생]
    D --> E[서버가 Webhook으로 POST 요청 전송]
    E --> F[클라이언트 Webhook이 요청 검증]
    F --> G[클라이언트가 tasks/get 호출하여 완전한 상태 검색]
    G --> H[작업 업데이트 처리]

보안 고려사항

서버 측 보안 조치

⚠️ 중요한 보안 알림 서버는 클라이언트가 제공한 Webhook URL을 맹목적으로 신뢰해서는 안 되며 다음 보안 조치를 구현해야 합니다:

  1. URL 검증

    • 신뢰할 수 있는 도메인 화이트리스트 유지
    • 소유권 검증 메커니즘 구현
    • 네트워크 송신 제어 사용

  2. 인증

    • Bearer Token (OAuth 2.0)
    • API Key 인증
    • HMAC 서명 검증
    • 상호 TLS (mTLS)

클라이언트 측 보안 조치

## 클라이언트 Webhook 보안 체크리스트

✅ 서버 신원 확인 (JWT 서명, HMAC 등)
✅ PushNotificationConfig.token 확인
✅ 재생 공격 방지를 위한 타임스탬프 검증 구현
✅ 중복 처리 방지를 위한 고유 ID (nonce) 사용
✅ 안전한 키 관리 및 순환

확장 메커니즘 심화 분석 {#extensions}

확장 시스템 아키텍처

A2A의 확장 시스템은 기본 호환성을 깨뜨리지 않고 핵심 프로토콜 위에 사용자 정의 기능을 추가할 수 있게 합니다. 확장은 URI로 식별되며 버전 관리와 종속성 관계를 지원합니다.

확장 타입 분류

확장 타입 설명 사용 예시
데이터 확장 AgentCard에만 구조화된 정보 추가 GDPR 준수 정보, 서비스 약관
프로필 확장 핵심 프로토콜에 구조 및 상태 요구사항 추가 의료 데이터 암호화, FHIR 표준
메서드 확장 완전히 새로운 RPC 메서드 추가 작업 히스토리 검색, 배치 작업

확장 선언 예시

{
  "name": "Magic 8-ball",
  "capabilities": {
    "extensions": [
      {
        "uri": "https://example.com/ext/konami-code/v1",
        "description": "새로운 운세를 잠금 해제하는 치트 코드 제공",
        "required": false,
        "params": {
          "hints": [
            "심즈가 빠른 현금이 필요할 때",
            "부인할 수도 있지만, 우리는 그 소들의 증거를 봤습니다."
          ]
        }
      }
    ]
  }
}

확장 활성화 플로우

graph TD
    A[클라이언트가 확장 활성화 요청] --> B[X-A2A-Extensions 헤더 추가]
    B --> C[서버가 지원되는 확장 확인]
    C --> D[확장 종속성 검증]
    D --> E[호환 가능한 확장 활성화]
    E --> F[X-A2A-Extensions 응답 헤더 반환]
    F --> G[확장 로직 실행]

확장 개발 모범 사례

버전 관리 전략

## 확장 버전 관리 표준

- 버전 번호가 포함된 URI 경로 사용: `/ext/my-extension/v1`
- 호환성을 깨는 변경사항은 새로운 URI를 사용해야 함
- 서버는 다른 버전으로 자동 다운그레이드하면 안 됨
- 영구 식별자 서비스 사용 권장 (w3id.org 등)

패키징 및 배포

# 예시: Python 서버 통합
from konami_code_extension import CheatCodeHandler
from a2a.server import A2AServer, DefaultRequestHandler

extension = CheatCodeHandler()
extension.add_cheat(
    code="motherlode",
    hint="심즈가 빠른 현금이 필요할 때"
)

request_handler = DefaultRequestHandler(
    agent_executor=MyAgentExecutor(extension),
    task_store=InMemoryTaskStore(),
    extensions=[extension]
)

작업 생명주기 관리 {#task-lifecycle}

작업 상태 머신

A2A 프로토콜의 작업은 명확한 생명주기 상태 머신을 따르며, 복잡한 워크플로우 관리를 지원합니다.

graph TD
    A[작업 생성] --> B[working]
    B --> C{입력 필요?}
    C -->|예| D[input-required]
    C -->|아니오| E{인증 필요?}
    E -->|예| F[auth-required]
    E -->|아니오| G{작업 완료?}
    G -->|성공| H[completed]
    G -->|실패| I[failed]
    G -->|취소됨| J[canceled]
    D --> K[입력 수신] --> B
    F --> L[인증 완료] --> B

컨텍스트와 작업 관계

contextId의 역할

  • 논리적 그룹화: 여러 작업과 독립적인 메시지를 함께 구성
  • 컨텍스트 관리: LLM을 위한 지속적인 대화 컨텍스트 제공
  • 협업 지원: 공통 목표를 중심으로 한 다중 작업 협업 지원

작업 비재시작 원칙

💡 설계 철학 작업이 종료 상태에 도달하면 재시작할 수 없습니다. 이 설계는 다음과 같은 이점을 가져다줍니다:

  • 작업 불변성: 클라이언트가 작업과 그 상태를 안정적으로 참조할 수 있음
  • 명확한 작업 단위: 각 요청, 개선, 또는 후속 작업이 독립적인 작업이 됨
  • 구현 단순화: 기존 작업 재시작의 복잡성을 피함

작업 개선 및 후속 작업

병렬 후속 작업 예시

작업 1: 헬싱키 항공편 예약
(작업 1 완료 후)
작업 2: 작업 1을 기반으로 호텔 예약
작업 3: 작업 1을 기반으로 스노모빌 활동 예약
(작업 2 완료 후, 작업 3은 여전히 진행 중)
작업 4: 작업 2를 기반으로 호텔 예약에 스파 서비스 추가

아티팩트 참조 메커니즘

{
  "message": {
    "contextId": "ctx-conversation-abc",
    "referenceTaskIds": ["task-boat-gen-123"],
    "parts": [
      {
        "kind": "text",
        "text": "요트를 빨간색으로 만들 수 있나요?",
        "metadata": {
          "referenceArtifacts": [
            {
              "artifactId": "artifact-boat-v1-xyz",
              "taskId": "task-boat-gen-123"
            }
          ]
        }
      }
    ]
  }
}

아티팩트 변경 추적

전략 구현 장점
동일한 이름 개선 작업이 원본 아티팩트 이름 유지 클라이언트가 관계를 쉽게 식별
새 ID 각 변경에 대해 새로운 artifactId 생성 버전 고유성 보장
클라이언트 관리 클라이언트가 아티팩트 버전 체인 유지 유연한 버전 제어 전략

보안 고려사항 {#security}

푸시 알림 보안 아키텍처

graph TD
    A[A2A 서버] --> B[Webhook URL 검증]
    B --> C[클라이언트 인증]
    C --> D[서명된 알림 전송]
    D --> E[클라이언트 Webhook]
    E --> F[서버 신원 확인]
    F --> G[알림 토큰 확인]
    G --> H[재생 공격 방지 검증]
    H --> I[알림 처리]

JWT + JWKS 보안 플로우 예시

서버 측 구현

{
  "iss": "a2a-server.example.com",
  "aud": "client-webhook.example.com",
  "iat": 1640995200,
  "exp": 1640995500,
  "jti": "unique-notification-id-123",
  "taskId": "task-abc-456"
}

클라이언트 검증 단계

  1. Authorization 헤더에서 JWT 추출
  2. JWT 헤더의 kid (key ID) 확인
  3. A2A 서버의 JWKS 엔드포인트에서 공개 키 검색
  4. JWT 서명 검증
  5. 클레임 검증 (iss, aud, iat, exp, jti)
  6. PushNotificationConfig.token 확인

모범 사례 {#best-practices}

스트리밍 처리 모범 사례

✅ 권장 사례

  • 네트워크 변동을 처리하기 위한 클라이언트 버퍼링 메커니즘 구현
  • 재연결을 위한 지수 백오프 전략 사용
  • 대용량 아티팩트를 위한 청크 전송 구현
  • 사용자 친화적인 진행률 표시기 제공

비동기 작업 모범 사례

## Webhook 구현 체크리스트

✅ URL 소유권 검증 구현
✅ HTTPS 및 인증서 검증 사용
✅ 요청 서명 검증 구현
✅ 속도 제한 및 보호 메커니즘 추가
✅ 디버깅을 위한 모든 알림 이벤트 로깅
✅ 우아한 오류 처리 및 재시도 구현

확장 개발 모범 사례

사례 설명 이점
필수 확장 최소화 핵심 기능만 필수로 표시 클라이언트 호환성 유지
완전한 입력 검증 모든 확장 관련 데이터 검증 보안 및 안정성 향상
명확한 문서화 상세한 사양 문서 제공 채택 및 올바른 구현 촉진
버전 호환성 호환성을 깨는 변경사항 신중히 처리 기존 통합 보호

자주 묻는 질문 {#faq}

Q: 스트리밍 처리와 푸시 알림 중 어떻게 선택하나요?

A: 선택은 주로 작업 특성과 클라이언트 기능에 따라 달라집니다:

  • 스트리밍 처리: 실시간 피드백이 필요한 시나리오, 짧은 작업 실행 시간(분), 연결을 유지할 수 있는 클라이언트에 적합
  • 푸시 알림: 장기 실행 작업(시간/일), 모바일 애플리케이션, 서버리스 함수, 기타 긴 연결을 유지할 수 없는 시나리오에 적합

Q: 확장 종속성은 어떻게 관리되나요?

A: 확장 종속성은 확장 사양에서 선언되며, 클라이언트는 확장과 모든 필수 종속성을 활성화할 책임이 있습니다. 클라이언트가 필수 종속성을 요청하지 않으면 서버는 요청을 거부하고 적절한 오류를 반환해야 합니다.

Q: 작업 실패 후 어떻게 복구하나요?

A: 작업이 종료 상태에 도달하면 재시작할 수 없습니다. 복구가 필요한 경우:

  1. 동일한 contextId를 사용하여 새 요청 시작
  2. referenceTaskIds를 통해 실패한 작업 참조
  3. 새 작업에서 오류 복구 로직 처리

Q: 푸시 알림 신뢰성을 어떻게 보장하나요?

A: 푸시 알림 신뢰성 전략에는 다음이 포함됩니다:

  • 재시도 메커니즘 및 지수 백오프 구현
  • 전달 보장을 위한 메시지 큐 사용
  • 알림 상태 쿼리 인터페이스 제공
  • 대안으로 클라이언트 능동 폴링 구현

Q: 확장 버전 업그레이드 중 호환성을 어떻게 유지하나요?

A: 버전 업그레이드 전략:

  • 호환성을 깨지 않는 변경사항은 동일한 URI에서 업데이트 가능
  • 호환성을 깨는 변경사항은 새로운 URI를 사용해야 함
  • 서버는 여러 버전을 동시에 지원할 수 있음
  • 마이그레이션 가이드 및 전환 기간 지원 제공

요약 및 다음 단계

A2A 프로토콜의 고급 기능은 AI 에이전트 간의 복잡한 상호작용을 위한 강력한 인프라 지원을 제공합니다. 스트리밍 처리, 비동기 작업, 확장 메커니즘, 완전한 작업 생명주기 관리를 통해 개발자는 더 유연하고 신뢰할 수 있으며 확장 가능한 AI 에이전트 시스템을 구축할 수 있습니다.

즉시 실행 권장사항

  1. 기존 시스템 평가: 현재 AI 에이전트 상호작용 패턴을 분석하고 A2A 고급 기능의 이점을 얻을 수 있는 시나리오 식별
  2. 프로토타입 개발: 특정 사용 사례를 선택하고 스트리밍 처리 또는 푸시 알림을 위한 프로토타입 구현
  3. 보안 계획: 푸시 알림 및 Webhook 구현 계획을 위한 보안 전략 개발
  4. 확장 설계: 비즈니스별 요구사항을 고려하고 해당 확장 사양 설계

관련 리소스

이 글은 A2A 프로토콜 완전 가이드 시리즈의 파트 2로, 프로토콜의 고급 기능과 실제 적용에 중점을 둡니다. A2A 프로토콜이 계속 발전함에 따라 최신 기능과 모범 사례를 반영하여 이 가이드를 지속적으로 업데이트할 예정입니다.

🚀 빠른 시작 예제

기본 예제

  • A2A Samples: Hello World Agent (2025년 5월 28일)
    • A2A Python SDK를 사용한 Hello World 에이전트 구축 완전 가이드
    • 상세한 환경 설정 및 테스트 지침 포함

통화 변환 에이전트

🐍 Python 구현 예제

GitHub 통합

  • A2A Python Sample: Github Agent (2025년 6월 16일)
    • a2a-python을 사용하여 GitHub 에이전트 생성 및 연결
    • 코드 저장소 정보 쿼리 기능 구현

여행 계획 도우미

파일 채팅 워크플로우

Python 튜토리얼 시리즈

🟨 JavaScript/TypeScript 예제

영화 정보 에이전트

JavaScript SDK 튜토리얼

☕ Java 구현 예제

  • A2A Java Sample (2025년 6월 5일)
    • Maven 다중 모듈 아키텍처
    • Spring Boot 서버 SDK 구현
    • AI 번역 서비스 예제

🔧 프레임워크 통합 예제

ADK 통합

경비 상환 에이전트

CrewAI 통합

LangGraph 통합

🔗 프로토콜 통합 예제

MCP 프로토콜 통합

  • A2A MCP AG2 지능형 에이전트 예제 (2025년 7월 2일)

    • AG2 프레임워크를 사용하여 구축된 A2A 프로토콜 지능형 에이전트
    • MCP 프로토콜 및 YouTube 자막 처리 기능과의 통합

  • A2A MCP 통합 (2025년 6월 4일)

    • A2A 및 MCP 통합을 위한 단계별 가이드
    • Python SDK 및 OpenRouter를 사용한 AI 에이전트 구축

🛠️ 개발 도구 및 SDK

.NET SDK

  • A2A .NET SDK 종합 문서 (2025년 7월 3일)
    • Google A2A Protocol v0.2.1을 구현하는 .NET 라이브러리
    • ASP.NET Core 애플리케이션에 적합

디버깅 도구

📚 기술 사양 및 모범 사례

프로토콜 사양

비교 및 분석

커뮤니티 리소스

🌍 다국어 리소스

중국어 리소스

기타 언어

최신 A2A 프로토콜 개발 소식을 받아보고 에이전트 간 통신의 미래를 구축하는 AI 에이전트 개발자들의 성장하는 커뮤니티에 참여하세요.