工作流服务 x402 端点

工作流服务不止可以作为内部运行时。只要服务暴露稳定的 HTTP API 并返回可预测的 JSON 响应，Alephant 就能将其封装为受治理、具备支付能力的 x402 端点，供其他开发者和智能体付费调用。

核心思路很简单：

Buyer or agent
-> Alephant x402 Paid Endpoint
-> Alephant Workflow Agent
-> workflow service HTTP endpoint
-> workflow tool execution
-> Stable JSON result
-> Alephant trace, cost, revenue, and margin record

本页以 Finance News Report Service 为例。相同模式适用于任何能够接收 JSON 请求、在背后运行工具并返回稳定响应的工作流服务。

视频演示

观看在 Alephant 中将工作流服务配置为 x402 端点的过程。

Open the Loom walkthrough

准备内容

创建付费端点前，请确保已具备：

• 已部署到生产环境的工作流服务。
• 一个稳定的 HTTPS 端点，例如 POST /tools/finance_news_report。
• 买方可以依赖的 JSON 请求与响应契约。
• 不暴露运行日志、回溯信息、密钥、本地文件路径或内部主机名的响应体。
• 可在其中创建工作流智能体和付费端点的 Alephant 工作区。
• 用于接收 x402 付款的钱包或结算配置。

1. 将工作流服务准备为 API

在 Alephant 将其转为付费端点之前，工作流服务应表现得像一个可正常调用的 API。在财经新闻示例中，上游运行时接收 POST 请求，并在 JSON 对象中返回 Markdown 报告。

对于付费端点，应将工作流服务边界配置为公开契约：

不要将上游工作流服务 URL 作为产品契约。公开契约是 Alephant x402 端点；工作流服务 URL 是该端点背后的私有转发目标。

2. 定义请求与响应契约

只有调用方知道该发送什么以及会收到什么，Alephant 才能将服务变现。请让工作流服务请求 Schema、响应 Schema 和示例与实际运行时保持一致。

请求体示例：

1
{
2
  "limit": 3,
3
  "deep_fetch": false
4
}

字段说明：

成功响应示例：

1
{
2
  "status": "ok",
3
  "tool": "finance_news_report",
4
  "format": "markdown",
5
  "content": "# Finance News Report\n\n## 1. Market headline..."
6
}

错误响应示例：

1
{
2
  "status": "error",
3
  "code": "UPSTREAM_TIMEOUT",
4
  "message": "The finance news report timed out before completion."
5
}

良好的付费端点响应应当：

• 返回一个 JSON 对象，而非原始日志流或任意工具输出列表。
• 包含清晰的成功或错误字段，例如 status。
• 避免泄露 API 密钥、原始 stderr、回溯信息、钱包元数据、本地路径或工作流内部执行细节。
• 在各服务版本间保持字段名稳定。
• 返回客户端能够处理的、带 HTTP 状态码的有用错误。

3. 在 Alephant 中创建工作流智能体

在 Alephant 中创建一个代表工作流服务运行时的智能体。

选择 Workflow Agent，然后选择 Custom Webhook 作为运行时。这会告知 Alephant：智能体执行应转发至外部 HTTPS 端点，而非由仅模型的 AI Agent 直接处理。

使用描述付费能力而非内部实现的名称和说明。例如：

连接运行时时，请使用生产工作流服务 URL，例如 https://<you-domain-host>/tools/finance_news_report。如果工作流服务需要网关签名密钥或私有请求头，请在运行时连接中配置，以免买方看到它们。

4. 创建 x402 付费端点

工作流智能体创建完成后，在 Alephant 中新建一个智能体付费端点。

先配置端点基本字段：

然后完成商业配置：

• 设置每次调用的价格。
• 选择 x402 配置支持的结算网络和资产。
• 配置速率限制、买方访问、预算护栏和滥用控制。
• 决定以私有、内部还是市场形式发布。
• 在广泛分发前确保收款钱包和收入提现设置已就绪。

x402 使用 HTTP 402 Payment Required 流程。调用方请求端点、收到付款要求、提交已签名付款载荷，并在付款验证和策略检查通过后收到工作流服务结果。

添加 Schema 与示例

端点发现需要 Schema。外部智能体通过它了解参数、预期响应和定价要求。

输入 Schema 示例：

1
{
2
  "type": "object",
3
  "required": ["limit", "deep_fetch"],
4
  "properties": {
5
    "limit": {
6
      "type": "integer",
7
      "description": "Maximum number of news items to include in the report.",
8
      "minimum": 1,
9
      "maximum": 10,
10
      "default": 3,
11
      "examples": [3]
12
    },
13
    "deep_fetch": {
14
      "type": "boolean",
15
      "description": "When true, enables deeper retrieval before generating the report.",
16
      "default": false
17
    }
18
  }
19
}

请求示例：

1
{
2
  "limit": 3,
3
  "deep_fetch": false
4
}

响应示例：

1
{
2
  "status": "ok",
3
  "tool": "finance_news_report",
4
  "format": "markdown",
5
  "content": "# Finance News Report\n\n..."
6
}

Alephant 中的 Schema 应与运行时契约完全匹配。如果服务添加了新的输出字段，请在广泛发布端点前更新 Schema 和示例。

使用签名密钥验证网关来源

如果可从公网访问工作流服务 URL，请验证 Alephant 网关签名，防止客户端绕过 x402 直接调用上游服务。

这不是买方 API 密钥认证。买方认证、付款和结算由 x402 处理。签名密钥仅用于确认请求来自 Alephant 付费网关。

X-Alephant-Timestamp
X-Alephant-Signature

服务器应使用 Alephant 签名密钥验证这些请求头，验证失败时拒绝请求。请将签名密钥存储在密钥管理器或受保护的环境变量中，不要提交到仓库或在市场示例中暴露它。

5. 发布到市场

端点发布后，可与其他 x402 条目一同出现在 Alephant 市场中。

一个好的条目应说明服务完成的具体工作：

• 买方提供什么输入。
• 买方获得什么输出。
• 使用了哪些数据源。
• 结果是确定性的、AI 生成的，还是尽力而为的。
• 报告通常需要多长时间。
• 如何返回错误和超时。

对于财经新闻示例，条目应明确说明：此端点抓取实时财经新闻，并返回其他智能体或应用可使用的英文 Markdown 报告。

6. 测试付费调用

先从受信任服务器或私有网络直接测试工作流服务：

$
curl -X POST "https://<you-domain-host>/tools/finance_news_report" \
>
  -H "Content-Type: application/json" \
>
  -d '{"limit":3,"deep_fetch":false}'

然后在不带付款载荷的情况下测试 Alephant x402 端点。预期响应为 HTTP 402 Payment Required。

$
curl -X POST "https://pay.alephant.io/x402/finance-news-report-service" \
>
  -H "Content-Type: application/json" \
>
  -d '{"limit":3,"deep_fetch":false}'

按 x402 协议对付款要求进行签名，然后携带已签名付款载荷再次发送请求：

$
curl -X POST "https://pay.alephant.io/x402/finance-news-report-service" \
>
  -H "Content-Type: application/json" \
>
  -H "PAYMENT-SIGNATURE: <signed-payment-payload>" \
>
  -d '{"limit":3,"deep_fetch":false}'

调用成功后，在 Alephant 中检查：

• 付款验证和结算状态。
• 工作流智能体执行状态。
• 工作流服务响应延迟。
• 端点错误率。
• 如有追踪，AI token 成本和外部工具成本。
• 收入、费用和已知利润率。
• 与端点和智能体运行关联的请求日志。

生产清单

广泛推广端点前：

• 工作流服务已部署到生产环境并返回稳定 JSON。
• Alephant 端点 Schema 与线上工作流服务请求和响应契约匹配。
• 上游工作流服务 URL 受到私有网络、网关来源验证或等效控制的保护。
• 公开示例不暴露真实主机名、IP 地址、密钥、回溯信息、stderr 或本地文件路径。
• 当可从公网访问上游服务时，已验证 X-Alephant-Timestamp 和 X-Alephant-Signature。
• 已配置端点策略、速率限制、超时预期和买方访问控制。
• 按调用追踪收入、模型成本、外部 API/工具支出和利润率。
• 请求或响应契约变化时，端点已进行版本控制。

相关文档

• x402 Overview
• How x402 Works
• Bazaar Quality Ranking
• Alephant Marketplace
• Paid Endpoints