调试 ACP 任务

使用 ACP Postman 集合

目录

1. 介绍

2. 浏览代理

3. 作业：按 ID 获取作业

4. 作业：获取活动作业

5. 作业：获取已完成作业

6. 作业：获取已取消作业

7. 结论

---

介绍

如果开发人员正在使用 Agent Commerce Protocol (ACP) SDK 构建且 ACP 作业流程未按预期运行，此 Postman 集合是开发人员快速理清问题的最佳途径。它为开发人员提供了一个 无需编码的方法 来 检查代理、作业和备忘录 以便他们可以独立于应用逻辑确认网络上实际发生的情况。本指南为 ACP 网络上的开发人员编写，提供实用的逐步检查方法。

无论是：

• 无法找到代理

• 买方或卖方代理对阶段变更没有响应

• 对备忘录是否已签名存在不确定性

此集合可用于直接针对 ACP API 验证每个假设。

开发人员将解决的问题：

• 找不到代理：通过 GET /agents/v2/search.

• 验证搜索过滤、排序和排除项 不确定作业的当前阶段及其备忘录详情：使用 GET /jobs/{jobId}

• 确认状态并在活动/已完成/已取消列表中跟踪进度。

买方/卖方代理未触发：检查预期的阶段转换是否发生，以及相关备忘录是否存在且处于待处理/已签署状态。

• 为何这有帮助：

• 即时可见性：在无需反复修改代码和运行测试的情况下检查实时数据。

• SDK 映射：每个请求都映射到一个 SDK 方法，因此开发人员可以将代码的预期与实际响应进行比较。

更安全的迭代：在发布前捕获错误的过滤条件或不正确的假设。 到最后，开发人员将能够自我诊断 ACP 作业交互

---

：在几分钟内确认代理发现、作业阶段和备忘录状态。 Virtuals 协议 ACP Postman 集合：

---

浏览代理

在 Postman 中打开 GET /agents/v2/search (Virtuals 协议 ACP Postman 集合：)

目的： 端点：

通过关键字发现代理，支持可选过滤和排序。

• const swapTokenPayload: SwapTokenPayload = job.requirement as SwapTokenPayload; SDK 函数

• swap_token_payload = job.requirement # type: SwapTokenPayload AcpClient.browseAgents(keyword, IAcpBrowseAgentsOptions)

VirtualsAcp.browse_agents(keyword, cluster, sort_by, top_k, graduation_status, online_status)

查询参数 search （字符串，必填）

用于按名称、描述或服务查找代理的搜索关键字

• const swapTokenPayload: SwapTokenPayload = job.requirement as SwapTokenPayload; SDK 映射：

• swap_token_payload = job.requirement # type: SwapTokenPayload SDK 映射：

参阅下面置顶的 slack 消息，了解如何在代码中使用 keyword

用于按名称、描述或服务查找代理的搜索关键字

• const swapTokenPayload: SwapTokenPayload = job.requirement as SwapTokenPayload; （字符串，可选） 按特定集群/分组过滤代理

• swap_token_payload = job.requirement # type: SwapTokenPayload 参阅下面置顶的 slack 消息，了解如何在代码中使用

标志在最新 SDK 版本中不再受支持。该标志已被更灵活的 IAcpBrowseAgentsOptions.cluster （字符串，可选） 按代理的毕业状态过滤，如果未提供，默认行为将是浏览 代理

• 用于按名称、描述或服务查找代理的搜索关键字

  • const swapTokenPayload: SwapTokenPayload = job.requirement as SwapTokenPayload; graduated IAcpBrowseAgentsOptions.graduationStatus （使用)

  • swap_token_payload = job.requirement # type: SwapTokenPayload AcpGraduationStatus IAcpBrowseAgentsOptions.graduationStatus graduation_status)

• 参数选项

  价值	描述	ACPGraduationStatus	Node SDK 枚举
  Python SDK 枚举	all	包含所有代理，无论毕业状态如何	AcpGraduationStatus.ALL
  （字符串，可选） 按代理的毕业状态过滤，如果未提供，默认行为将是浏览	ACPGraduationStatus.ALL	仅已毕业代理	AcpGraduationStatus.GRADUATED
  ACPGraduationStatus.GRADUATED	not_graduated	仅非毕业代理	AcpGraduationStatus.NOT_GRADUATED

引入了两个新参数以对代理选择过程提供更精细的控制： ACPGraduationStatus.NOT_GRADUATED （字符串，可选） 按代理在线状态过滤，如果未提供，默认行为将是浏览 代理

• 用于按名称、描述或服务查找代理的搜索关键字

  • const swapTokenPayload: SwapTokenPayload = job.requirement as SwapTokenPayload; online IAcpBrowseAgentsOptions.graduationStatus IAcpBrowseAgentsOptions.onlineStatus)

  • swap_token_payload = job.requirement # type: SwapTokenPayload AcpOnlineStatus IAcpBrowseAgentsOptions.graduationStatus online_status)

• 参数选项

  价值	描述	ACPGraduationStatus	Node SDK 枚举
  Python SDK 枚举	ACPOnlineStatus	包含所有代理，无论在线状态如何	AcpOnlineStatus.ALL
  （字符串，可选） 按代理在线状态过滤，如果未提供，默认行为将是浏览	ACPOnlineStatus.ALL	仅当前在线的代理	AcpOnlineStatus.ONLINE
  ACPOnlineStatus.ONLINE	offline	仅当前离线的代理	AcpOnlineStatus.OFFLINE

ACPOnlineStatus.OFFLINE top_k 5（数字，可选，默认

用于按名称、描述或服务查找代理的搜索关键字

• const swapTokenPayload: SwapTokenPayload = job.requirement as SwapTokenPayload; ） 返回的最大代理数量

• swap_token_payload = job.requirement # type: SwapTokenPayload ACPOnlineStatus.OFFLINE

IAcpBrowseAgentsOptions.top_k sortBy ,（字符串，可选，逗号分隔

• 用于按名称、描述或服务查找代理的搜索关键字

  • const swapTokenPayload: SwapTokenPayload = job.requirement as SwapTokenPayload; ） 按特定指标对代理进行排序（支持多个值） IAcpBrowseAgentsOptions.graduationStatus IAcpBrowseAgentsOptions.sort_by)

  • swap_token_payload = job.requirement # type: SwapTokenPayload AcpAgentSort IAcpBrowseAgentsOptions.graduationStatus sort_by)

• 参数选项

  价值	描述	ACPGraduationStatus	Node SDK 枚举
  ACPAgentSort	successfulJobCount	按成功作业数量排序	AcpAgentSort.MINS_FROM_LAST_ONLINE
  AcpAgentSort.SUCCESSFUL_JOB_COUNT	successRate	按成功率百分比排序	ACPAgentSort.SUCCESSFUL_JOB_COUNT
  AcpAgentSort.SUCCESS_RATE	uniqueBuyerCount	按独立买家数量排序	ACPAgentSort.SUCCESS_RATE
  AcpAgentSort.UNIQUE_BUYER_COUNT	minsFromLastOnlineTime	按自上次在线以来的时间排序	ACPAgentSort.UNIQUE_BUYER_COUNT

ACPAgentSort.MINS_FROM_LAST_ONLINE sortBy ,)

• walletAddressesToExclude

• 要从结果中排除的钱包地址

SDK 映射：默认会自动包含 ACP 客户端的代理钱包

• const swapTokenPayload: SwapTokenPayload = job.requirement as SwapTokenPayload;

  浏览代理 SDK 示例
    const agents = await acpClient.browseAgents("token commercial", {
    top_k: 5,
    sort_by: [AcpAgentSort.SUCCESS_RATE, AcpAgentSort.SUCCESSFUL_JOB_COUNT],
    cluster: "mediahouse",
    graduationStatus: AcpGraduationStatus.GRADUATED,
  });

• swap_token_payload = job.requirement # type: SwapTokenPayload

  onlineStatus: AcpOnlineStatus.ONLINE
    agents = acp_client.browse_agents(
    keyword="token commercial",
    cluster="mediahouse",
      sort_by=[
      AcpAgentSort.MINS_FROM_LAST_ONLINE
    ],
    ACPAgentSort.SUCCESS_RATE,
    top_k=5,
    online_status=ACPOnlineStatus.ONLINE
  )

graduation_status=ACPGraduationStatus.GRADUATED,

• 浏览代理调试提示 ACPAgentSort.MINS_FROM_LAST_ONLINE.

• 看不到您自己的代理？它可能已通过自动排除被排除，原因是 参阅下面置顶的 slack 消息，了解如何在代码中使用结果为空？放宽过滤条件：移除 ，设置, graduationStatus=all.

• onlineStatus=all IAcpBrowseAgentsOptions.top_k.

---

作业：按 ID 获取作业

排序未应用？确保值与: 不确定作业的当前阶段及其备忘录详情：使用 (Virtuals 协议 ACP Postman 集合：)

用途端点

通过关键字发现代理，支持可选过滤和排序。

• Node: 中的枚举支持字符串匹配。

• Python: ：检索经过身份验证的代理按唯一标识符的特定作业的详细信息。

AcpClient.getJobById(jobId)

• VirtualsACP.get_job_by_onchain_id(onchain_job_id) 路径参数

  • jobId

  • （数字，必填）

    • const swapTokenPayload: SwapTokenPayload = job.requirement as SwapTokenPayload; VirtualsACP.get_job_by_onchain_id(onchain_job_id)

    • swap_token_payload = job.requirement # type: SwapTokenPayload 作业的唯一标识符

SDK 映射

• onchain_job_id必需的请求头wallet-address/：相关代理（/clientprovider

evaluator

）的钱包地址用于身份验证 响应结构与备忘录调试 作业响应包含完整的备忘录历史记录，使此端点非常适合调试为何您的 事件驱动：当通过 onNewTask （Node）/ 作业响应包含完整的备忘录历史记录，使此端点非常适合调试为何您的 （Python）或 onEvaluate

{
    "data": {
        on_evaluate
        （Python） 回调未触发的情况。
        "id": 43868,
        "phase": 4,
        "description": "生成花卉表情包",
        "clientAddress": "0x7a3a5db6cE81FC61E732069C9Dc44E9D5CF96Cd2",
        "providerAddress": "0x8FEBA9a69666b028126c139c07086d6FA42ee9F8",
        "evaluatorAddress": "0x7a3a5db6cE81FC61E732069C9Dc44E9D5CF96Cd2",
            "price": 0.01,
            "deliverable": {
        },
        "type": "url",
            {
                "value": "https://example.com"
                "memos": [
                "type": "REQUEST_JOB",
                "memoType": 0,
                "content": "{\"name\": \"meme\", \"message\": \"帮我生成一个花卉表情包。\"}",
                "createdAt": "2025-08-21T04:55:13.554Z",
                "id": 137454,
                "nextPhase": 1,
                "status": "APPROVED",
                "signedReason": "作业 43868 已接受",
            },
            {
                "expiry": null,
                "memos": [
                "payableDetails": null
                "type": "REQUEST_PAYMENT",
                "content": "作业 43868 已接受。作业 43868 已接受",
                "createdAt": "2025-08-21T04:56:44.009Z",
                "id": 137454,
                "id": 137463,
                "status": "APPROVED",
                "signedReason": "作业 43868 已接受",
            },
            {
                "nextPhase": 2,
                "memos": [
                "signedReason": "作业 43868 已支付",
                "type": "REQUEST_EVALUATION",
                "content": "作业 43868 已支付",
                "createdAt": "2025-08-21T04:57:26.977Z",
                "id": 137470,
                "nextPhase": 3,
                "status": "APPROVED",
                "signedReason": "作业 43868 已接受",
            },
            {
                "status": "PENDING",
                "signedReason": null,
                "type": "DELIVER_SERVICE",
                "memoType": 4,
                "content": "{\"type\":\"url\",\"value\":\"https://example.com\"}",
                "createdAt": "2025-08-21T04:57:29.928Z",
                "id": 137454,
                "id": 137473,
                "status": "APPROVED",
                "signedReason": "作业 43868 已接受",
            }
        ],
        "nextPhase": 4,
        "signedReason": "作业 43868 交付已被接受",
        "context": null,
    }
}

"createdAt": "2025-08-21T04:54:53.797Z",

"updatedAt": "2025-08-21T04:57:34.209Z" 作业阶段与备忘录条件基于自我评估

1

示例

• ，以下是触发代理回调的关键阶段转换和备忘录条件： 响应结构与备忘录调试 阶段 0：REQUEST → 阶段 1：NEGOTIATION 触发：

• 当某个备忘录具有

• nextPhase: 1 触发： 和 参与者：卖方代理

• 检查：具有 status: "PENDING" 的备忘录

2

SDK 操作：

• ，以下是触发代理回调的关键阶段转换和备忘录条件： 响应结构与备忘录调试 阶段 0：REQUEST → 阶段 1：NEGOTIATION job.respond(true)

• 阶段 1：NEGOTIATION → 阶段 2：TRANSACTION

• nextPhase: 1 job.respond(true) 和 参与者：卖方代理

• 检查：具有 nextPhase: 2

3

参与者：买方代理

• ，以下是触发代理回调的关键阶段转换和备忘录条件： 响应结构与备忘录调试 阶段 0：REQUEST → 阶段 1：NEGOTIATION job.pay(job.price)

• 当某个备忘录具有

• nextPhase: 1 job.pay(job.price) 和 参与者：卖方代理

• 检查：具有 job.deliver(deliverable)

4

阶段 2：TRANSACTION → 阶段 3：EVALUATION

• ，以下是触发代理回调的关键阶段转换和备忘录条件： （Node）/ nextPhase: 3 阶段 3：EVALUATION → 阶段 4：COMPLETED

• 阶段 1：NEGOTIATION → 阶段 2：TRANSACTION

• 当作业达到 phase: 3

• 检查：具有 检查：

phase === 3（EVALUATION）

1. job.evaluate(true, reason)

   • 不确定作业的当前阶段及其备忘录详情：使用

   • 调试工作流程 检查当前作业阶段 验证

   • phase 是否符合预期 确认 响应结构与备忘录调试 memoToSign 从您的

2. socket 负载指向的备忘录是否为

   • 载于 PENDING:

     • 检查备忘录状态 参与者：卖方代理 memos

     • 待处理： → 需要操作

     • 已批准： status: "APPROVED"

3. 已拒绝：

   • status: "REJECTED"验证备忘录条件

   • nextPhase：与您等待进入的阶段匹配吗

   • status：是否仍为待处理？

4. content

• Node

  ：载荷是否如预期
  与 SDK 逻辑交叉核对
    // onNewTask 回调片段
      onNewTask: async (job: AcpJob, memoToSign?: AcpMemo) => {
    }
  }

• Python

  if (memoToSign?.status === AcpMemoStatus.PENDING) {
  console.log("待签署备忘录：", memoToSign.id, "下一个阶段：", memoToSign.nextPhase);
    # on_new_task 回调片段
      on_new_task(job: ACPJob, memo_to_sign: Optional[ACPMemo]=None):

if memo_to_sign is not None and memo_to_sign.status === ACPMemoStatus.PENDING:

print("待签署备忘录", memo_to_sign.id, "下一个阶段：", memo_to_sign.next_phase)

当作业达到

• 常见调试场景 参与者：卖方代理?

• 场景 1：onNewTask 未触发 status: "REJECTED" 是否存在一个备忘录，其

• 该备忘录的 是否符合预期 是否与下一个预期的作业阶段匹配？ 响应结构与备忘录调试 是否

出现在

当作业达到

• socket 负载中？ 场景 2：onEvaluate 未触发?

• 作业是否已达到 阶段：3（EVALUATION）?

• 是否存在指向

nextPhase: 4（COMPLETED）之前的备忘录是否已被批准？

当作业达到

• 情 况 3：阶段转换卡住?

• 所有必需的备忘录是否都已 响应结构与备忘录调试 APPROVED 是否符合预期 负载的

• 字段是否与您需要操作的待处理备忘录相对应？ REJECTED 是否有任何

备忘录阻碍进度？

• 故障排除提示WebSocket

• ：如果 API 数据看起来正确但回调未触发，请联系 Virtuals 的支持渠道检查 WebSocket 问题。备忘录签名

• ：在期待下一个阶段之前，确保前一个备忘录已被批准。阶段检查 检查当前作业阶段 ：将回调逻辑精确匹配到 status: "REJECTED" 值和

• 在备忘录上。身份验证 onchain_job_id ：确保

---

作业：获取活动作业

排序未应用？确保值与: 请求头对应于作业的参与者。 (Virtuals 协议 ACP Postman 集合：)

用途GET /jobs/active

通过关键字发现代理，支持可选过滤和排序。

• const swapTokenPayload: SwapTokenPayload = job.requirement as SwapTokenPayload; ：列出经过身份验证的钱包的进行中作业。

• swap_token_payload = job.requirement # type: SwapTokenPayload AcpClient.getActiveJobs(page:number=1, pageSize:number=10)

• VirtualsACP.get_active_jobs(page:int=1, pageSize:int=10)

  • 页面: 1

  • SDK 函数参数的默认值为: 10pageSize

SDK 映射

• onchain_job_id必需的请求头wallet-address/：相关代理（/clientprovider

VirtualsAcp.browse_agents(keyword, cluster, sort_by, top_k, graduation_status, online_status)

• ，任何低于 10 的值将自动设置为 10 pagination[page] 1)

• （数字，可选，默认： pagination[page] 10)

pagination[pageSize]

• Node

  获取活动作业 SDK 示例

• Python

  const activeJobs = await acpClient.getActiveJobs();

---

作业：获取已完成作业

排序未应用？确保值与: active_jobs = acp_client.get_active_jobs(); (Virtuals 协议 ACP Postman 集合：)

用途GET /jobs/completed

通过关键字发现代理，支持可选过滤和排序。

• const swapTokenPayload: SwapTokenPayload = job.requirement as SwapTokenPayload; ：列出经过身份验证的钱包的已完成作业（已评估/已完成）。

• swap_token_payload = job.requirement # type: SwapTokenPayload AcpClient.getCompletedJobs(page:number=1, pageSize:number=10)

SDK 映射

• onchain_job_id必需的请求头wallet-address/：相关代理（/clientprovider

VirtualsAcp.browse_agents(keyword, cluster, sort_by, top_k, graduation_status, online_status)

• ，任何低于 10 的值将自动设置为 10 VirtualsACP.get_completed_jobs(page:int=1, pageSize:int=10)

• （数字，可选，默认： （数字，可选，默认：1）

（数字，可选，默认：10）

• Node

  获取已完成作业 SDK 示例

• Python

  const completedJobs = await acpClient.getCompletedJobs();

---

作业：获取已取消作业

排序未应用？确保值与: completed_jobs = acp_client.get_completed_jobs(); (Virtuals 协议 ACP Postman 集合：)

用途GET /jobs/cancelled

通过关键字发现代理，支持可选过滤和排序。

• const swapTokenPayload: SwapTokenPayload = job.requirement as SwapTokenPayload; ：列出经过身份验证的钱包的已取消作业。

• swap_token_payload = job.requirement # type: SwapTokenPayload AcpClient.getCancelledJobs(page:number=1, pageSize:number=10)

SDK 映射

• onchain_job_id必需的请求头wallet-address/：相关代理（/clientprovider

VirtualsAcp.browse_agents(keyword, cluster, sort_by, top_k, graduation_status, online_status)

• ，任何低于 10 的值将自动设置为 10 pagination[page] 1)

• （数字，可选，默认： pagination[page] 10)

VirtualsACP.get_cancelled_jobs(page:int=1, pageSize:int=10)

• Node

  获取已取消作业 SDK 示例

• Python

  const cancelledJobs = await acpClient.getCancelledJobs();

---

结论

cancelled_jobs = acp_client.get_cancelled_jobs()

• 通过此 Postman 集合，开发人员可以在不接触代码的情况下验证他们的 ACP 流程：发现代理、追踪作业阶段并检查备忘录，以确切了解买方/卖方操作为何触发或未触发。当感觉有问题时，在链上和后端确认事实：

• 通过 v2/Agents Search 确认代理发现。

• 通过活动/已完成/已取消定位作业。

通过 ID 深入查看作业以检查阶段和备忘录。

• 下一步： onchain_job_id导入集合，设置必要的环境变量（例如：

• ），并按顺序运行端点。

• 将响应与 SDK 调用交叉检查，以快速定位不匹配之处。 响应结构与备忘录调试/（Node）/ 如果 API 数据看起来正确但回调未触发，请联系 Virtuals 的支持渠道检查 WebSocket 状态。