EvoCloud Agent Toolkit

EvoCloud Agent Toolkit 是一个综合的 Python SDK，专为将 EvoCloud 支付服务与 AI 代理和应用程序集成而设计。

特性

• 🤖 LangChain 集成: 为构建对话式支付体验提供结构化工具
• 🔧 MCP 支持: 支持模型上下文协议（Model Context Protocol）
• 💰 完整的支付功能: 支持订单创建、查询、退款等全流程操作
• 🎯 简单易用: 统一的 SDK 接口，支持多种使用方式
• 🔒 安全可靠: 内置签名验证和错误处理
• 📦 批量操作: 支持批量创建和查询订单
• 🛠️ 开发友好: 完整的类型提示和文档

安装

pip install evocloud-agent-toolkit

快速开始

MCP 服务器

运行 MCP 服务器：

基础使用

from evocloud_agent_toolkit import EvoCloudSDK

# 初始化 SDK
sdk = EvoCloudSDK(
    base_url="https://api.evocloud.com",
    sign_key="your_sign_key",
    sid="your_sid",
    webhook_url="https://your-domain.com/webhook"  # 可选
)

# 生成订单号
order_id = sdk.generate_order_id("PAYMENT")
print(f"Generated order ID: {order_id}")

# 创建支付订单
order_result = sdk.create_linkpay_order(
    merchant_order_id=order_id,
    currency="USD",
    amount="99.99",
    goods_name="Premium Service",
    goods_description="Monthly subscription",
    return_url="https://your-domain.com/return"
)

if order_result["success"]:
    print(f"Payment URL: {order_result['data']['link_url']}")
else:
    print(f"Order creation failed: {order_result['message']}")

# 查询订单状态
status_result = sdk.query_linkpay_order(order_id)
print(f"Order status: {status_result}")

环境变量配置

创建 .env 文件：

EVOCLOUD_BASE_URL=https://api.evocloud.com
EVOCLOUD_SIGN_KEY=your_sign_key
EVOCLOUD_SID=your_sid
EVOCLOUD_WEBHOOK_URL=https://your-domain.com/webhook

然后可以简化 SDK 初始化：

from evocloud_agent_toolkit import EvoCloudSDK

# 自动从环境变量读取配置
sdk = EvoCloudSDK()

LangChain 集成

from evocloud_agent_toolkit import EvoCloudSDK
from langchain.agents import initialize_agent, AgentType
from langchain.llms import OpenAI

# 初始化 SDK
sdk = EvoCloudSDK()

# 获取 LangChain 工具
tools = sdk.get_langchain_tools()

# 创建 LangChain 代理
llm = OpenAI(temperature=0)
agent = initialize_agent(
    tools, 
    llm, 
    agent=AgentType.STRUCTURED_CHAT_ZERO_SHOT_REACT_DESCRIPTION,
    verbose=True
)

# 使用代理处理支付请求
response = agent.run("Create a payment order for $50 USD for a premium subscription")
print(response)

高级功能

批量操作

# 批量创建订单
orders = [
    {
        "currency": "USD",
        "amount": "29.99",
        "goods_name": "Product A"
    },
    {
        "currency": "USD", 
        "amount": "49.99",
        "goods_name": "Product B"
    }
]

results = sdk.create_multiple_orders(orders)
for result in results:
    print(f"Order: {result}")

# 批量查询订单
order_ids = ["ORDER_123", "ORDER_456", "ORDER_789"]
statuses = sdk.query_multiple_orders(order_ids)
for status in statuses:
    print(f"Status: {status}")

退款操作

# 创建退款
refund_result = sdk.create_linkpay_refund(
    original_merchant_order_id="ORDER_123",
    currency="USD",
    refund_amount="29.99",
    reason="CUSTOMER_REQUEST",
    description="Customer requested refund"
)

if refund_result["success"]:
    refund_id = refund_result["data"]["merchant_trans_id"]
    print(f"Refund created: {refund_id}")
    
    # 查询退款状态
    refund_status = sdk.query_linkpay_refund(refund_id)
    print(f"Refund status: {refund_status}")

健康检查和配置

# 获取当前配置
config = sdk.get_config()
print(f"SDK Configuration: {config}")

# 执行健康检查
health = sdk.health_check()
if health["success"]:
    print("SDK is healthy!")
else:
    print(f"Health check failed: {health['message']}")

API 参考

EvoCloudSDK

主要的 SDK 客户端类，提供所有支付功能的统一接口。

初始化参数

• base_url: EvoCloud API 基础 URL
• sign_key: 签名密钥
• sid: 系统 ID
• sign_type: 签名算法类型（默认: SHA256）
• timeout: 请求超时时间（默认: 60 秒）
• max_retries: 最大重试次数（默认: 0）
• webhook_url: 默认回调地址（可选）
• auto_configure: 是否自动从环境变量配置（默认: True）

主要方法

工具方法

• generate_order_id(prefix="LINKPAY"): 生成唯一订单号
• get_current_time(): 获取当前时间（ISO 格式）
• get_config(): 获取当前配置
• health_check(): 执行健康检查

支付操作

• create_linkpay_order(**kwargs): 创建 LinkPay 支付订单
• query_linkpay_order(merchant_order_id): 查询订单状态
• create_linkpay_refund(**kwargs): 创建退款
• query_linkpay_refund(merchant_trans_id): 查询退款状态

批量操作

• create_multiple_orders(orders): 批量创建订单
• query_multiple_orders(order_ids): 批量查询订单

LangChain 集成

• get_langchain_toolkit(): 获取 LangChain 工具包
• get_langchain_tools(): 获取 LangChain 工具列表
• get_linkpay_tool(): 获取 LinkPay 工具实例

错误处理

SDK 提供了完善的错误处理机制：

try:
    result = sdk.create_linkpay_order(
        currency="USD",
        amount="invalid_amount"  # 无效金额
    )
except ValueError as e:
    print(f"参数错误: {e}")
except Exception as e:
    print(f"其他错误: {e}")

# 也可以通过返回结果检查
result = sdk.create_linkpay_order(currency="USD", amount="99.99")
if not result["success"]:
    print(f"操作失败: {result['message']}")
    print(f"错误详情: {result['data']['error']}")

环境变量

变量名	描述	必需
EVOCLOUD_BASE_URL	EvoCloud API 基础 URL	是
EVOCLOUD_SIGN_KEY	签名密钥	是
EVOCLOUD_SID	系统 ID	是
EVOCLOUD_WEBHOOK_URL	默认回调地址	否

开发

安装开发依赖

pip install -e ".[dev]"

运行测试

pytest

代码格式化

black .
isort .

类型检查

mypy evocloud_agent_toolkit

示例

查看 examples/ 目录中的完整示例：

• basic_usage.py: 基础使用示例
• langchain_integration.py: LangChain 集成示例
• batch_operations.py: 批量操作示例
• error_handling.py: 错误处理示例

贡献

欢迎提交 Pull Request 和 Issue！

许可证

MIT License. 详见 LICENSE 文件。

支持

• 📖 文档
• 🐛 问题反馈
• 💬 讨论

更新日志

v0.1.0

• ✨ 初始版本发布
• 🤖 支持 LangChain 集成
• 💰 完整的 LinkPay 支付功能
• 📦 支持批量操作
• 🛠️ 完善的开发工具链