A2A Protocol

AP2 (Agent Payments Protocol) 사용 튜토리얼

English日本語한국어中文
MILO•
Share
AP2Python
AP2 (Agent Payments Protocol) Usage Tutorial

개요

AP2 (Agent Payments Protocol)는 사람이 참석하는 경우와 참석하지 않는 경우 모두의 상거래 플로우를 지원하는 에이전트 결제 프로토콜입니다. 이 튜토리얼은 AP2 Python 샘플 프로젝트 사용 방법에 대해 자세히 설명합니다.

프로젝트 구조

samples/python/
├── src/ap2/                    # AP2 핵심 코드
├── scenarios/                  # 사용 시나리오 예제
│   └── a2a/human-present/     # 사람 참석 결제 시나리오
│       ├── cards/             # 카드 결제 예제
│       └── x402/              # x402 결제 예제
├── pyproject.toml             # 프로젝트 설정
└── README.md                  # 프로젝트 설명

환경 요구사항

  • Python 3.10+
  • uv 패키지 매니저
  • Google API Key (AI 기능용)

설치 단계

1. uv 패키지 매니저 설치

아직 uv를 설치하지 않았다면 uv 설치 가이드를 방문하여 설치하세요.

2. 프로젝트 클론 및 의존성 설치

# 프로젝트 클론
git clone https://github.com/google-agentic-commerce/AP2.git

# 프로젝트 디렉토리로 이동
cd AP2/samples/python

# 의존성 설치
uv sync

3. Google API Key 설정

Google AI Studio에서 API 키를 획득한 후, 다음 방법 중 하나를 선택하여 설정하세요:

환경 변수

export GOOGLE_API_KEY=your_api_key_here

핵심 개념

1. 주요 액터 (Key Actors)

  • Shopping Agent (쇼핑 에이전트): 주요 조정자로, 사용자 쇼핑 요청을 처리하고 전문 에이전트에게 위임
  • Merchant Agent (상인 에이전트): 쇼핑 에이전트로부터의 제품 쿼리를 처리
  • Merchant Payment Processor Agent (상인 결제 처리 에이전트): 상인을 대신하여 결제를 처리
  • Credentials Provider Agent (자격증명 제공자 에이전트): 사용자 결제 자격증명을 관리

2. 핵심 데이터 구조

  • IntentMandate: 구매 의도 정보를 포함하는 의도 권한
  • CartMandate: 견적 정확성을 보장하기 위해 상인이 서명한 쇼핑카트 권한
  • PaymentMandate: 거래 정보와 사용자 서명을 포함하는 결제 권한

사용 시나리오

시나리오 1: 사람 참석 카드 결제

사용자가 참석하여 구매 세부사항과 결제 방법을 확인하는 가장 일반적인 결제 시나리오입니다.

단계별 실행

각 서비스를 다른 터미널에서 실행하고 싶다면:

  1. 상인 에이전트 시작
# AP2/samples/python
uv run --package ap2-samples python -m roles.merchant_agent
  1. 자격증명 제공자 시작
# AP2/samples/python
uv run --package ap2-samples python -m roles.credentials_provider_agent
  1. 상인 결제 처리 에이전트 시작
# AP2/samples/python
uv run --package ap2-samples python -m roles.merchant_payment_processor_agent
  1. 쇼핑 에이전트 시작
# AP2/samples/python
uv run --package ap2-samples adk web src/roles

상호작용 플로우

  1. 인터페이스 접근: 브라우저에서 http://0.0.0.0:8000/dev-ui 방문
  2. 에이전트 선택: 드롭다운 메뉴에서 shopping_agent 선택
  3. 요청 시작: "커피머신을 사고 싶습니다"와 같은 구매 의도 입력
  4. 제품 검색: 쇼핑 에이전트가 상인 에이전트에게 위임하여 매칭 제품 검색
  5. 카트 생성: 상인 에이전트가 CartMandate를 생성하고 쇼핑 에이전트와 공유
  6. 제품 선택: 표시된 제품 중에서 선택
  7. 자격증명 제공자 연결: 선호하는 자격증명 제공자에 연결
  8. 결제 방법 선택: 사용 가능한 결제 방법 중에서 선택
  9. 결제 권한 생성: 쇼핑 에이전트가 PaymentMandate를 생성하고 서명 요청
  10. OTP 인증: 시뮬레이션된 OTP 123 입력
  11. 구매 완료: 확인 메시지와 디지털 영수증 수신

시나리오 2: x402 결제

x402 호환 결제 방법을 지원합니다 (완전한 AP2 호환 버전은 곧 출시 예정).

실행 방법은 카드 결제 시나리오와 유사하지만 x402 관련 스크립트와 설정을 사용합니다.

고급 기능

1. 상세 모드 (Verbose Mode)

에이전트의 내부 작동을 이해하기 위해 상세 모드를 활성화할 수 있습니다:

새 신발을 사고 싶습니다. 전체 과정에서 상세 모드를 유지하고, 무엇을 하고 있는지 설명하며 모든 데이터 페이로드를 표시해 주세요.

상세 모드에서는 다음이 표시됩니다:

  • 현재 및 다음 단계의 상세 설명
  • 모든 데이터 페이로드의 JSON 표현
  • 생성, 전송 또는 수신되는 권한 객체

2. 에이전트 통신 로그

시스템은 .logs 디렉토리에 상세한 로그 파일 watch.log를 자동으로 생성합니다.

로그에는 세 가지 범주의 데이터가 포함됩니다:

범주 내용
원시 HTTP 데이터 HTTP 메서드, URL, JSON 요청 본문 및 응답 본문
A2A 메시지 데이터 A2A 메시지의 TextPart에서 추출된 요청 지시사항과 DataParts의 데이터
AP2 프로토콜 데이터 메시지 DataParts에서 식별된 권한 객체

코드 아키텍처

1. 메시지 빌더

A2aMessageBuilder 클래스는 A2A 메시지 구축에 사용됩니다:

builder = A2aMessageBuilder()
message = builder.add_text("Hello").add_data("key", data).build()

2. 기본 서버 실행자

BaseServerExecutor는 에이전트의 기본 기능을 제공합니다:

  • 요청 및 응답 처리
  • 확장 기능 관리
  • 도구 파싱 및 실행

3. 결제 검증

시스템에는 거래 보안을 보장하기 위한 결제 권한 검증 로직이 포함되어 있습니다:

def validate_payment_mandate_signature(payment_mandate: PaymentMandate) -> None:
    if payment_mandate.user_authorization is None:
        raise ValueError("User authorization not found in PaymentMandate.")

4. Credentials Provider Agent 코드 설명

이 에이전트는 "디지털 지갑" 역할을 하며, 사용자의 결제 방법과 배송 주소 저장/검색, 결제 과정에서 "결제 자격증명 토큰" 생성 및 검증을 담당합니다. 핵심 코드는 samples/python/src/roles/credentials_provider_agent/에 위치합니다:

  • 진입점: __main__.py

    • 로컬 agent.json 설명을 agent_card로 로드.
    • 포트 8002에서 서비스 시작, RPC 경로는 /a2a/credentials_provider.
    • CredentialsProviderExecutor를 생성하고 지원되는 확장 기능 목록을 전달.

  • 실행자: agent_executor.py

    • CredentialsProviderExecutor는 BaseServerExecutor를 상속하며, 시스템 프롬프트에 의해 "도구 호출만 출력, 사용자와 잡담 금지"로 제한.
    • 등록된 도구에는 다음이 포함됩니다:
      • handle_get_shipping_address
      • handle_search_payment_methods
      • handle_create_payment_credential_token
      • handle_signed_payment_mandate
      • handle_get_payment_method_raw_credentials

  • 도구 세트: tools.py

    • 공통 데이터 키:
      • 배송 주소 키: CONTACT_ADDRESS_DATA_KEY
      • 결제 권한 키: PAYMENT_MANDATE_DATA_KEY
      • 상인 허용 결제 방법 데이터 키: PAYMENT_METHOD_DATA_DATA_KEY
    • 주요 처리 함수:
      • handle_get_shipping_address
        • 입력: user_email
        • 액션: 계정 관리자에서 해당 배송 주소를 조회하여 CONTACT_ADDRESS_DATA_KEY에 출력.
      • handle_search_payment_methods
        • 입력: user_email과 PaymentMethodData 세트 (카드 네트워크 등 상인 허용 조건).
        • 액션: 내부 매칭 로직(_payment_method_is_eligible)을 호출하여 상인 조건을 충족하는 사용자 계정 결제 방법을 필터링, {"payment_method_aliases": [...]}를 반환.
      • handle_create_payment_credential_token
        • 입력: user_email, payment_method_alias.
        • 액션: 선택된 결제 방법에 대한 일회용 "결제 자격증명 토큰"을 생성, {"token": "fake_payment_credential_token_x"}와 같은 형식으로 반환.
      • handle_signed_payment_mandate
        • 입력: PaymentMandate (payment_mandate_id와 결제 세부사항의 token 포함).
        • 액션: 서명된 payment_mandate_id를 이전에 생성된 token에 바인딩, 후속 검증용.
      • handle_get_payment_method_raw_credentials
        • 입력: PaymentMandate (payment_mandate_id와 token 포함).
        • 액션: token과 payment_mandate_id의 일관성을 검증하고, 기본 원시 결제 자격증명(예: 카드 네트워크, DPAN/암호화 데이터 등)을 반환하여 결제 처리업체가 청구를 완료할 수 있도록 함.

  • 계정 및 토큰 관리: account_manager.py

    • 여러 계정을 시뮬레이션하는 인메모리 데이터베이스, 예제에는 다음이 포함됩니다:
      • 사용자의 shipping_address
      • 여러 payment_methods (CARD, BANK_ACCOUNT, DIGITAL_WALLET 등), 카드에는 네트워크와 청구 주소 등이 포함.
    • 토큰 생명주기:
      • create_token(email, alias): 토큰 생성 및 저장 (이메일과 결제 방법 별칭 매핑).
      • update_token(token, payment_mandate_id): 서명된 payment_mandate_id를 토큰에 바인딩 (한 번만 쓰기).
      • verify_token(token, payment_mandate_id): 토큰과 권한 ID가 일치하는지 검증, 해당 결제 방법의 "원시 자격증명"을 반환.
    • 계정 조회 기능:
      • get_account_shipping_address(email)
      • get_account_payment_methods(email)
      • get_payment_method_by_alias(email, alias)

  • 에이전트 기능 선언: agent.json

    • capabilities.extensions는 AP2 확장 기능과 샘플 카드 네트워크 확장 기능 지원을 선언.
    • skills는 외부 기능("사용 가능한 결제 방법 조회", "배송 주소 가져오기" 등)을 설명.

일반적인 상호작용 시퀀스 (요약)

  1. 쇼핑 에이전트가 상인 허용 PaymentMethodData와 user_email을 제공하고, search_payment_methods를 호출하여 사용 가능한 payment_method_aliases를 가져옴.
  2. payment_method_alias를 선택하고, create_payment_credential_token을 호출하여 token을 가져옴.
  3. 쇼핑 에이전트가 PaymentMandate를 생성하고 사용자 서명을 요청, 서명 완료 후 반환하면 자격증명 제공자가 signed_payment_mandate를 사용하여 payment_mandate_id를 token에 바인딩.
  4. 상인 결제 처리 에이전트가 결제 완료 전에 get_payment_method_raw_credentials를 호출하여 token + payment_mandate_id를 사용해 검증하고 기본 원시 결제 자격증명과 교환.

참고: 위의 데이터 키 상수는 ap2.types 모듈에서 정의됩니다; 도구 간에는 TaskUpdater를 통해 DataPart 아티팩트를 출력하여 상위 에이전트가 계속 오케스트레이션할 수 있도록 합니다.

확장 기능 개발

1. 새로운 결제 방법 생성

새로운 결제 방법을 지원하려면:

  1. agent.json에서 확장 기능 지원 선언
  2. 해당 처리 로직 구현
  3. 검증 규칙 업데이트

2. 새로운 에이전트 역할 추가

새로운 에이전트 생성에는:

  1. BaseServerExecutor 상속
  2. 필요한 도구 함수 구현
  3. 에이전트 설명 파일 설정

문제 해결

일반적인 문제

  1. Google API Key 오류

    • API Key가 올바르게 설정되었는지 확인
    • API Key가 유효한지 확인

  2. 포트 충돌

    • 필요한 포트(8000-8003)가 점유되지 않았는지 확인
    • 설정 파일에서 포트 설정을 수정할 수 있음

  3. 의존성 설치 실패

    • Python 버전이 >= 3.10인지 확인
    • 캐시 정리 시도: uv cache clean

디버깅 팁

  1. watch.log 파일을 확인하여 상세한 통신 과정 이해
  2. 상세 모드를 사용하여 더 많은 디버깅 정보 획득
  3. 각 서비스의 콘솔 출력 확인

모범 사례

  1. 보안: 결제 권한의 서명을 항상 검증
  2. 오류 처리: 포괄적인 오류 처리 메커니즘 구현
  3. 로그 기록: 디버깅과 감사를 위한 주요 작업 기록
  4. 테스트: 프로덕션 환경 전에 모든 결제 플로우를 충분히 테스트

요약

AP2는 강력하고 유연한 에이전트 결제 프로토콜 프레임워크를 제공합니다. 이 튜토리얼을 통해 다음을 할 수 있어야 합니다:

  • AP2의 핵심 개념과 아키텍처 이해
  • 샘플 프로젝트 성공적으로 실행
  • 사용자 정의 결제 에이전트 개발
  • 일반적인 문제와 문제 해결 처리

더 자세한 정보는 프로젝트 내의 구체적인 코드 구현과 주석을 참조하세요.

AP2 (Agent Payments Protocol) 사용 튜토리얼