A commerce-centric demo featuring Agent Development Kit with Paypal Agent Toolkit via MCPs

一个以商务为核心的演示：通过 MCP 使用 Agent Development Kit 和 Paypal Agent Toolkit

这个 4 分钟的演示展示了如何通过 MCP 使用 PayPal 的 Agent Toolkit 和 Google 的 Agent Development Kit，快速开展对话式售前互动。

Paypal Sandbox

在 developer.paypal.com 注册后，你可以设置多个应用，每个应用都附带：

• 供应用调用 API 的 Client ID 和 Secret Key。
• 一个沙盒账户，包含可用于登录 sandbox.paypal.com 的邮箱和密码。
• 沙盒账户包含可用于测试交易的测试信用卡、地址和银行详细信息。

使用 Paypal API 的注意事项

可用 API

这些 API 主要面向商家，共有 25 个 API，涵盖：

• 争议
• 发票
• 订单
• 订阅
• 物流跟踪
• 交易

本演示中

本演示仅使用以下 API，它们已经过测试并确认可正常运行。 演示中仅包含订单和物流：

• 'orders.create',
• 'orders.get',
• 'orders.capture',
• 'shipment.create',
• 'shipment.get',
• 'subscriptions.create',
• 'subscriptions.show',
• 'subscriptions.cancel'

请参阅 arch/paypal_mcp_adk_a2a.svg，了解演示结尾提到远程 Agent 的部分。 这些外部 Agent 可以单独定义，代码也存放在别处；但借助 A2A，你的 Agent 可以利用这些外部 Agent 的智能为客户提供服务，而无需了解它们是如何构建的。

API 依赖关系

以下是 API 之间的依赖关系和操作注意事项：

• 创建订单会返回一个付款 URL，供用户登录并手动付款。
• 只有在消费者完成交易后，调用订单捕获才会成功。
• 商家调用接受争议申诉之前，必须先由用户在沙盒环境中创建争议。
• 只有事先创建了产品和订阅计划，才能创建订阅。
• list_transactions 显示最新交易时会有延迟。

设置

Python 包

需要 Google ADK 0.3.0+：

python3 -m venv ~/.ppmcp_adk
source ~/.ppmcp_adk/bin/activate
pip install "google-adk==0.3.0"
pip install "google-cloud-aiplatform==1.90.0"

或者，如果你更倾向于使用 poetry：

poetry install

MCP 客户端

从 Node.js 网站安装 nodejs 和 npx

确保配置类似以下内容，使 node 和 npx 位于 PATH 中：

$ which node
/Users/USERNAME/.nvm/versions/node/v22.14.0/bin/node

$ which npx
/Users/USERNAME/.nvm/versions/node/v22.14.0/bin/npx

配置

将 'env.example' 复制为 '.env' 并设置 '.env` 文件：

• 填入以下任一项：你的 Google API Key，或你的 Google Cloud Project ID 和 Location
• 找到并填入 Paypal Sandbox PAYPAL_CLIENT_ID 和 PAYPAL_SECRET

填入 Paypal 沙盒中实际存在的订单信息：

• 在 paypal_mcp_agent/util.py 中的函数 load_user_profile() 内。
• 修改 user_profile 和 orders 字典。 这些数据会在 before_agent_callback 期间加载。

运行 ADK Developer UI

1. 在工作目录 pp_mcp_adk 中运行 adk web，该目录下需有 .env 文件。
2. 你会看到 INFO: Uvicorn running on http://0.0.0.0:8000 (Press CTRL+C to quit)
3. 在浏览器中访问 http://localhost:8000/dev-ui?app=paypal_mcp_agent

示例交互

[用户]：我订购的狗玩具到哪儿了？

[Agent]：[调用 get_shipment_tracking API]

[Agent]：您的 Dido Dog Toy 订单（ID：2RH052419P314283P）已于 2025-04-24 通过 UPS 发货，跟踪号码为 1Z1234567890123456。

[用户]：那也给我看看订单信息吧？

[Agent]：[调用 get_order API]

[Agent]：以下是您的订单信息：

• 订单 ID：2RH052419P314283P
• 状态：COMPLETED
• 商品：Dido Dog Toy
• 数量：3
• 总金额：30.00 USD
• 收货地址：1 Main St，San Jose，CA 95131，US

[用户]：（手动点击聊天框左侧的回形针图标，将绿色连衣裙图片加载到聊天框中。该图片位于 ./paypal_mcp_agent/images，然后说……）推荐一款风格相似、更加正式的款式。

[Agent]：好的，我明白了。您想找一款更正式、但与您发送的图片中的连衣裙风格相似的款式。 ……图片中的连衣裙具有以下特点：

[Agent]：[调用 product_search 工具]

……

[Agent]：我找到三款您可能感兴趣的连衣裙：

……

[用户]：我喜欢第二款连衣裙！

[Agent]：太好了……您想订购它吗？

[用户]：是的，就这么办。

[Agent]：[调用 create_order API]

[Agent]：您的 Floral Mermaid Summer Dress 订单已下单！

订单详情如下：

订单 ID：7EK45304FF8688429
商品名称：Floral Mermaid Summer Dress
价格：220 USD
付款链接：https://www.sandbox.paypal.com/checkoutnow?token=7EK45304FF8688429