KUNGFU TECH

0
0
Lập trình
Admin Team
Admin Teamtechmely

Hướng dẫn sử dụng AP2 (Giao thức Thanh toán Đại lý)

Đăng vào 2 ngày trước

• 10 phút đọc

Chủ đề:

#agent#a2a#ap2

Giới thiệu

AP2 (Giao thức Thanh toán Đại lý) là một giao thức cho phép thanh toán đại lý, hỗ trợ cả quy trình thương mại có người hiện diện và không có người hiện diện. Hướng dẫn này cung cấp các hướng dẫn chi tiết về cách sử dụng dự án mẫu Python của AP2.

Cấu trúc dự án

Copy 
samples/python/
├── src/ap2/                    # Mã nguồn chính của AP2
├── scenarios/                  # Ví dụ về kịch bản sử dụng
│   └── a2a/human-present/     # Kịch bản thanh toán có người hiện diện
│       ├── cards/             # Ví dụ thanh toán bằng thẻ
│       └── x402/              # Ví dụ thanh toán x402
├── pyproject.toml             # Cấu hình dự án
└── README.md                  # Tài liệu dự án

Yêu cầu môi trường

  • Python 3.10+
  • Trình quản lý gói uv
  • Google API Key (để sử dụng chức năng AI)

Các bước cài đặt

1. Cài đặt Trình quản lý gói uv

Nếu bạn chưa cài đặt uv, vui lòng truy cập hướng dẫn cài đặt uv để biết các bước chi tiết.

2. Nhân bản dự án và Cài đặt các phụ thuộc

Copy 
# Nhân bản dự án
git clone https://github.com/google-agentic-commerce/AP2.git

# Chuyển đến thư mục dự án
cd AP2/samples/python

# Cài đặt các phụ thuộc
uv sync

3. Cấu hình Google API Key

Lấy một API Key từ Google AI Studio, sau đó chọn một trong các phương pháp cấu hình sau:

Biến Môi Trường

Copy 
export GOOGLE_API_KEY=your_api_key_here

Các khái niệm chính

1. Các tác nhân chính

  • Đại lý mua sắm: Điều phối viên chính xử lý yêu cầu mua sắm của người dùng và phân công cho các đại lý chuyên biệt.
  • Đại lý thương mại: Xử lý truy vấn sản phẩm từ các đại lý mua sắm.
  • Đại lý xử lý thanh toán thương mại: Xử lý thanh toán thay mặt cho các nhà bán hàng.
  • Đại lý cung cấp thông tin xác thực: Quản lý thông tin xác thực thanh toán của người dùng.

2. Cấu trúc dữ liệu chính

  • IntentMandate: Ủy quyền ý định chứa thông tin ý định mua hàng.
  • CartMandate: Ủy quyền giỏ hàng được ký bởi thương mại để đảm bảo độ chính xác của báo giá.
  • PaymentMandate: Ủy quyền thanh toán chứa thông tin giao dịch và chữ ký của người dùng.

Các kịch bản sử dụng

Kịch bản 1: Thanh toán bằng thẻ có người hiện diện

Đây là kịch bản thanh toán phổ biến nhất, nơi người dùng hiện diện để xác nhận chi tiết mua hàng và phương thức thanh toán.

Hướng dẫn từng bước

Nếu bạn muốn chạy mỗi dịch vụ trong các terminal khác nhau:

  1. Khởi động Đại lý Thương mại
Copy 
# AP2/samples/python
uv run --package ap2-samples python -m roles.merchant_agent
  1. Khởi động Đại lý Cung cấp Thông tin Xác thực
Copy 
# AP2/samples/python
uv run --package ap2-samples python -m roles.credentials_provider_agent
  1. Khởi động Đại lý Xử lý Thanh toán Thương mại
Copy 
# AP2/samples/python
uv run --package ap2-samples python -m roles.merchant_payment_processor_agent
  1. Khởi động Đại lý Mua sắm
Copy 
# AP2/samples/python
uv run --package ap2-samples adk web src/roles

Luồng tương tác

  1. Truy cập Giao diện: Mở trình duyệt và truy cập http://0.0.0.0:8000/dev-ui
  2. Chọn Đại lý: Chọn shopping_agent từ menu dropdown
  3. Khởi tạo Yêu cầu: Nhập ý định mua sắm, ví dụ "Tôi muốn mua một máy pha cà phê"
  4. Tìm kiếm Sản phẩm: Đại lý mua sắm phân công cho đại lý thương mại để tìm các sản phẩm phù hợp
  5. Tạo Giỏ hàng: Đại lý thương mại tạo CartMandate và chia sẻ với đại lý mua sắm
  6. Chọn Sản phẩm: Chọn từ các sản phẩm được hiển thị
  7. Liên kết với Đại lý Cung cấp Thông tin Xác thực: Kết nối với nhà cung cấp thông tin xác thực mà bạn chọn
  8. Chọn Phương thức Thanh toán: Chọn từ các phương thức thanh toán có sẵn
  9. Tạo Ủy quyền Thanh toán: Đại lý mua sắm tạo PaymentMandate và yêu cầu chữ ký
  10. Xác thực OTP: Nhập OTP giả lập 123
  11. Hoàn tất Mua hàng: Nhận thông báo xác nhận và biên lai điện tử

Kịch bản 2: Thanh toán x402

Hỗ trợ các phương thức thanh toán tương thích x402 (phiên bản đầy đủ tương thích AP2 sẽ sớm ra mắt).

Phương thức khởi động tương tự như kịch bản thanh toán bằng thẻ, nhưng sử dụng các kịch bản và cấu hình liên quan đến x402.

Tính năng nâng cao

1. Chế độ Verbose

Để hiểu rõ các hoạt động bên trong của các đại lý, bạn có thể bật chế độ verbose:

Copy 
Tôi muốn mua một đôi giày mới. Vui lòng ở chế độ verbose trong suốt quá trình, giải thích những gì bạn đang làm và hiển thị tất cả dữ liệu.

Chế độ verbose sẽ hiển thị:

  • Giải thích chi tiết về các bước hiện tại và tiếp theo
  • Các đại diện JSON của tất cả tải dữ liệu
  • Các đối tượng ủy quyền đang được tạo, gửi hoặc nhận

2. Nhật ký giao tiếp của Đại lý

Hệ thống tự động tạo các tệp nhật ký chi tiết watch.log trong thư mục .logs.

Nhật ký chứa ba loại dữ liệu:

Danh mục Nội dung
Dữ liệu HTTP Thô Phương thức HTTP, URL, các thân yêu cầu và phản hồi JSON
Dữ liệu Tin nhắn A2A Hướng dẫn yêu cầu trích xuất từ Tin nhắn A2A và dữ liệu trong các DataParts
Dữ liệu Giao thức AP2 Các đối tượng ủy quyền được xác định trong các DataParts của tin nhắn

Kiến trúc mã

1. Trình tạo Tin nhắn

Lớp A2aMessageBuilder được sử dụng để xây dựng các tin nhắn A2A:

Copy 
builder = A2aMessageBuilder()
message = builder.add_text("Xin chào").add_data("key", data).build()

2. Trình thực thi Máy chủ Cơ bản

BaseServerExecutor cung cấp các chức năng cơ bản cho các đại lý:

  • Xử lý yêu cầu và phản hồi
  • Quản lý các phần mở rộng
  • Phân tích và thực thi công cụ

3. Xác thực Thanh toán

Hệ thống bao gồm logic xác thực ủy quyền thanh toán để đảm bảo an toàn giao dịch:

Copy 
def validate_payment_mandate_signature(payment_mandate: PaymentMandate) -> None:
    if payment_mandate.user_authorization is None:
        raise ValueError("Không tìm thấy ủy quyền của người dùng trong PaymentMandate.")

4. Giải thích mã của Đại lý Cung cấp Thông tin Xác thực

Đại lý này hoạt động như một "ví điện tử", có trách nhiệm lưu trữ/lấy các phương thức thanh toán và địa chỉ giao hàng của người dùng, cũng như tạo và xác thực các "mã thông báo xác thực thanh toán" trong quá trình thanh toán. Mã chính nằm trong samples/python/src/roles/credentials_provider_agent/:

  • Điểm vào: __main__.py

    • Tải mô tả agent.json cục bộ như agent_card.
    • Khởi động dịch vụ trên cổng 8002 với đường dẫn RPC /a2a/credentials_provider.
    • Tạo CredentialsProviderExecutor và truyền vào danh sách các phần mở rộng được hỗ trợ.

  • Trình thực thi: agent_executor.py

    • CredentialsProviderExecutor kế thừa từ BaseServerExecutor, bị ràng buộc bởi lời nhắc hệ thống là "chỉ xuất các cuộc gọi công cụ, không trò chuyện bình thường với người dùng."
    • Các công cụ đã đăng ký bao gồm:
    • handle_get_shipping_address
    • handle_search_payment_methods
    • handle_create_payment_credential_token
    • handle_signed_payment_mandate
    • handle_get_payment_method_raw_credentials

  • Bộ công cụ: tools.py

    • Các khóa dữ liệu chung:

    • Khóa địa chỉ giao hàng: CONTACT_ADDRESS_DATA_KEY

    • Khóa ủy quyền thanh toán: PAYMENT_MANDATE_DATA_KEY

    • Khóa dữ liệu các phương thức thanh toán được thương mại chấp nhận: PAYMENT_METHOD_DATA_DATA_KEY

    • Các hàm xử lý khóa:

    • handle_get_shipping_address

      • Đầu vào: user_email
      • Hành động: Truy vấn địa chỉ giao hàng tương ứng từ quản lý tài khoản, xuất ra CONTACT_ADDRESS_DATA_KEY.

    • handle_search_payment_methods

      • Đầu vào: user_email và một tập hợp các PaymentMethodData (các điều kiện chấp nhận của thương mại như mạng thẻ).
      • Hành động: Gọi logic khớp nội bộ (_payment_method_is_eligible) để lọc các phương thức thanh toán của tài khoản người dùng mà đáp ứng các điều kiện thương mại, trả về {"payment_method_aliases": [...]}.

    • handle_create_payment_credential_token

      • Đầu vào: user_email, payment_method_alias.
      • Hành động: Tạo một mã thông báo "thông tin xác thực thanh toán" một lần cho phương thức thanh toán đã chọn, trả về định dạng như {"token": "fake_payment_credential_token_x"}.

    • handle_signed_payment_mandate

      • Đầu vào: PaymentMandate (chứa payment_mandate_id và token trong chi tiết thanh toán).
      • Hành động: Liên kết payment_mandate_id đã ký với mã thông báo đã tạo trước đó để xác thực sau này.

    • handle_get_payment_method_raw_credentials

      • Đầu vào: PaymentMandate (chứa payment_mandate_id và token).
      • Hành động: Xác thực sự nhất quán của token và payment_mandate_id, trả về thông tin xác thực thanh toán thô (ví dụ: mạng thẻ, DPAN/dữ liệu mã hóa) để bộ xử lý thanh toán hoàn tất giao dịch.

  • Quản lý tài khoản và mã thông báo: account_manager.py

    • Cơ sở dữ liệu trong bộ nhớ mô phỏng nhiều tài khoản, ví dụ bao gồm:
    • Địa chỉ giao hàng của người dùng
    • Nhiều payment_methods (chẳng hạn như CARD, BANK_ACCOUNT, DIGITAL_WALLET), thẻ chứa mạng và địa chỉ thanh toán, v.v.
    • Vòng đời mã thông báo:
    • create_token(email, alias): Tạo và lưu mã thông báo (liên kết email và phương thức thanh toán).
    • update_token(token, payment_mandate_id): Liên kết payment_mandate_id đã ký với mã thông báo (chỉ ghi một lần).
    • verify_token(token, payment_mandate_id): Xác thực xem mã thông báo có khớp với ID ủy quyền hay không, trả về "thông tin xác thực thô" của phương thức thanh toán đó.
    • Các khả năng truy vấn tài khoản:
    • get_account_shipping_address(email)
    • get_account_payment_methods(email)
    • get_payment_method_by_alias(email, alias)

  • Khai báo khả năng của đại lý: agent.json

    • capabilities.extensions khai báo hỗ trợ cho các phần mở rộng AP2 và các phần mở rộng mạng thẻ mẫu.
    • skills mô tả các khả năng bên ngoài (như "truy vấn các phương thức thanh toán có sẵn", "lấy địa chỉ giao hàng").

Chuỗi tương tác điển hình (Tóm tắt)

  1. Đại lý mua sắm cung cấp các PaymentMethodData được thương mại chấp nhận và user_email, gọi search_payment_methods để lấy các payment_method_aliases có sẵn.
  2. Chọn một payment_method_alias, gọi create_payment_credential_token để lấy token.
  3. Đại lý mua sắm tạo PaymentMandate và yêu cầu chữ ký của người dùng, sau khi hoàn tất chữ ký trả nó, đại lý cung cấp thông tin xác thực sử dụng signed_payment_mandate để liên kết payment_mandate_id với token.
  4. Đại lý xử lý thanh toán thương mại gọi get_payment_method_raw_credentials trước khi hoàn tất thanh toán, sử dụng token + payment_mandate_id để xác thực và đổi lấy thông tin xác thực thanh toán thô.

Lưu ý: Các hằng số khóa dữ liệu trên được định nghĩa trong mô-đun ap2.types; các công cụ xuất DataPart thông qua TaskUpdater để các đại lý upstream tiếp tục điều phối.

Phát triển mở rộng

1. Tạo các Phương thức Thanh toán Mới

Để hỗ trợ các phương thức thanh toán mới, bạn cần:

  1. Khai báo hỗ trợ mở rộng trong agent.json
  2. Triển khai logic xử lý tương ứng
  3. Cập nhật quy tắc xác thực

2. Thêm Các Vai trò Đại lý Mới

Việc tạo các đại lý mới yêu cầu:

  1. Kế thừa từ BaseServerExecutor
  2. Triển khai các chức năng công cụ cần thiết
  3. Cấu hình tệp mô tả đại lý

Khắc phục sự cố

Vấn đề phổ biến

  1. Lỗi API Key Google

    • Đảm bảo API Key được thiết lập chính xác
    • Kiểm tra xem API Key có hợp lệ không

  2. Xung đột cổng

    • Đảm bảo các cổng cần thiết (8000-8003) không bị chiếm giữ
    • Bạn có thể thay đổi cài đặt cổng trong các tệp cấu hình

  3. Lỗi cài đặt phụ thuộc

    • Đảm bảo phiên bản Python >= 3.10
    • Thử xóa bộ nhớ cache: uv cache clean

Mẹo Gỡ lỗi

  1. Kiểm tra tệp watch.log để hiểu rõ quy trình giao tiếp chi tiết
  2. Sử dụng chế độ verbose để có thêm thông tin gỡ lỗi
  3. Kiểm tra đầu ra của từng dịch vụ trên console

Thực tiễn tốt nhất

  1. An ninh: Luôn xác thực chữ ký ủy quyền thanh toán
  2. Xử lý lỗi: Triển khai các cơ chế xử lý lỗi toàn diện
  3. Ghi nhật ký: Ghi lại các thao tác quan trọng để gỡ lỗi và kiểm toán
  4. Kiểm tra: Kiểm tra kỹ lưỡng tất cả các quy trình thanh toán trước khi đưa vào sản xuất

Kết luận

AP2 cung cấp một khung giao thức thanh toán đại lý mạnh mẽ và linh hoạt. Thông qua hướng dẫn này, bạn sẽ có thể:

  • Hiểu các khái niệm và kiến trúc chính của AP2
  • Chạy thành công dự án mẫu
  • Phát triển các đại lý thanh toán tùy chỉnh
  • Xử lý các vấn đề phổ biến và gỡ lỗi

Để biết thêm thông tin chi tiết, vui lòng tham khảo các triển khai mã cụ thể và các nhận xét trong dự án.

Xem quảng cáo để đọc tiếpHoặc nâng cấp tài khoản để tắt quảng cáo

Nội dung bài viết

Gợi ý câu hỏi phỏng vấn
Không có dữ liệu

Không có dữ liệu

Bài viết được đề xuất
Bài viết cùng tác giả

Bình luận

Chưa có bình luận nào

Chưa có bình luận nào