教程

本教程在一台机器上设置两个 ANet 节点，并完成二者之间一次收费的能力调用。其中一个节点是提供方，发布一个小型文本摘要服务，每次调用收取 2 额度；另一个节点是请求方，负责发现该服务、为一次调用付费，并检查结果、回执和支出。

教程包括以下步骤：

1. 创建两个身份。

2. 将两个节点注册到 Hub。

3. 编写服务并将其发布为能力。

4. 查找该能力并读取其卡片。

5. 调用该能力并确认首次支付。

6. 对已知的提供方允许自动支付。

7. 检查结果并验证回执。

8. 读取送达状态。

9. 查看支出。

前提条件

• 已按 安装 所述安装 anet，且 anet doctor 未报告失败的检查项。

• 有可用的 Hub。示例使用 https://hub.example.com，请替换为实际使用的 Hub 的地址。关于 Hub，本教程涉及两点：

  • 如果 Hub 按 AID 准入，其运维者需要为每个节点运行一条 anet-hub admit 命令，并可通过 --grant 附加初始余额。请求方需要有额度才能为调用付费。

  • 如果 Hub 开放注册，则不会出现准入步骤。新账号处于 72 小时的试用期，试用期结束后才会获得试用额度。在此之前，请求方无法完成本教程中的支付。

• 示例服务需要 python3。

两个节点运行在同一台机器上，各自拥有独立的身份、数据目录和控制端口。若要在两台机器上运行，请在两台机器上都安装 anet，从所有命令中去掉 --id 选项，并在各自的机器上运行对应角色的命令。

创建两个身份

anet id new 在 ~/.anet/ids 之下创建带独立数据目录的具名身份，并为其启动守护进程。

$ anet id new provider
Creating identity "provider" …
anet 0.3.0 is running in the background: identity provider …x3j42pdi (data directory /home/user/.anet/ids/provider).
hub       Not joined to a hub yet, so nothing can be sent or received; run anet hub-register https://hub.agentnetwork.org.cn to join the official public hub, or use your organization's hub URL instead.
  → anet hub-register https://hub.agentnetwork.org.cn
...
$ anet id new requester
Creating identity "requester" …
anet 0.3.0 is running in the background: identity requester …q7m2k9ab (data directory /home/user/.anet/ids/requester).
hub       Not joined to a hub yet, so nothing can be sent or received; run anet hub-register https://hub.agentnetwork.org.cn to join the official public hub, or use your organization's hub URL instead.
  → anet hub-register https://hub.agentnetwork.org.cn
...

每条命令都以新节点的状态结束。hub 行说明尚未加入任何 hub。列表显示两个身份及各自的控制端口：

$ anet id ls
   NAME           STATE    CONTROL            AID                    DATA DIR
   provider       running  127.0.0.1:39811    bafyreick…             /home/user/.anet/ids/provider
   requester      running  127.0.0.1:39812    bafyreigi…             /home/user/.anet/ids/requester

anet --id NAME COMMAND 为某一个身份运行任意命令。每个节点的 AID 由 anet status --json 输出。以下命令将两个 AID 存入 shell 变量，供本教程其余部分使用：

$ PROVIDER=$(anet --id provider status --json | sed -n 's/^  "aid": "\(.*\)",$/\1/p')
$ REQUESTER=$(anet --id requester status --json | sed -n 's/^  "aid": "\(.*\)",$/\1/p')
$ echo "$PROVIDER"
bafyrei...

将两个节点注册到 Hub

anet hub-register 将身份添加到 Hub。守护进程提交密钥事件日志和加密密钥集合，Hub 验证该节点确实控制该身份。

$ anet --id provider hub-register https://hub.example.com --name tutorial-provider
This identity has no recovery passphrase yet: if its data directory leaks, the identity can be taken over and cannot be recovered. Run anet identity protect in a terminal.
  → anet identity protect
This hub (https://hub.example.com) needs its operator to admit your AID first; send this line to the operator: anet-hub admit <provider-aid> (once they do, this node finishes joining on its own).
  → anet-hub admit <provider-aid>

在按 AID 准入的 Hub 上，最后一行是给运维者的命令。注册在后台重试，并在运维者运行该命令后的短时间内完成。请求方以同样方式注册：

$ anet --id requester hub-register https://hub.example.com --name tutorial-requester

Hub 的运维者此时准入两个 AID，并向请求方附加初始余额。这些命令在 Hub 所在主机上运行；Hub 的数据目录不在工作目录时，用 --data 指定。

$ anet-hub admit <provider-aid>
Admitted <provider-aid>; it finishes joining on its own once it runs anet hub-register.
$ anet-hub admit <requester-aid> --grant 20
Admitted <requester-aid>; the 20-credit grant is paid when it first registers.

等待两个节点都报告状态 registered：

$ anet --id provider status --json | grep -A1 '"state": "registered"'
    "state": "registered",
    "reason": "registered",

恢复口令

hub-register 输出中的警告有其原因。在终端中运行该命令时，首次注册会请求输入恢复口令，并写入加密的恢复文件。口令只在终端输入，守护进程从不读取。轮换密钥、将身份迁移到另一个 Hub 以及在另一台机器上恢复身份，都需要该口令，而 ANet 无法找回它。

没有终端可用时（例如由编程 Agent 运行该命令），注册仍会完成，身份也可立即使用。此时恢复种子仅由数据目录内的密钥保护，身份状态为未受保护，anet status 和 anet doctor 会重复该警告。在终端上运行 anet identity protect 可设置口令并替换恢复种子，此前已复制的种子随之失效。在此之前，数据目录一旦泄露，身份就可能被接管。各状态及相关命令参见 身份与 KEL。

编写服务并发布

能力是一个可供其他节点调用的名称，加上一个负责应答的本地服务。service 模块把二者连接起来：守护进程以 HTTP POST 将调用参数作为 JSON 对象发送，并期望返回 JSON 对象。服务无需了解 ANet。

本教程中的服务返回文本的 SHA-256 摘要。它监听 Unix 域套接字，这是推荐的形式：守护进程在向套接字写入任何内容之前，会检查该路径只能由受信任的账户修改，且监听进程以套接字所有者的身份运行。

将以下内容保存为 digest_service.py：

import hashlib
import json
import os
import socketserver
from http.server import BaseHTTPRequestHandler

SOCKET = os.path.expanduser("~/.anet-tutorial/digest.sock")


class UnixHTTPServer(socketserver.UnixStreamServer):
    def get_request(self):
        request, _ = super().get_request()
        return request, ("local", 0)


class Handler(BaseHTTPRequestHandler):
    def do_POST(self):
        length = int(self.headers.get("Content-Length", "0"))
        args = json.loads(self.rfile.read(length) or b"{}")
        text = str(args.get("text", ""))
        reply = {
            "sha256": hashlib.sha256(text.encode()).hexdigest(),
            "bytes": len(text.encode()),
        }
        body = json.dumps(reply).encode()
        self.send_response(200)
        self.send_header("Content-Type", "application/json")
        self.send_header("Content-Length", str(len(body)))
        self.end_headers()
        self.wfile.write(body)


os.makedirs(os.path.dirname(SOCKET), mode=0o700, exist_ok=True)
if os.path.exists(SOCKET):
    os.unlink(SOCKET)
UnixHTTPServer(SOCKET, Handler).serve_forever()

在另一个终端中启动它，并直接调用一次以确认其可用：

$ python3 digest_service.py
$ curl -s --unix-socket ~/.anet-tutorial/digest.sock \
    -X POST -d '{"text":"hello"}' http://localhost/digest
{"sha256": "2cf24dba5fb0a30e26e83b2ac5b9e29e1b161e5c1fa7425e73043362938b9824", "bytes": 5}

发布需要在提供方的配置中添加两个条目：

modules.service.capabilities

声明能力：其标识符、服务的 URL、以额度计的价格和描述。价格为 0 或未设价格，表示该能力免费。

inbound.public_capabilities

列出名单之外的调用方可以调用的能力标识符。已声明但未在此列出的能力不会出现在公开卡片上。

以下命令将两个条目添加到提供方的配置中。它会读取现有文件，因此其他键保持不变。

$ python3 - <<'EOF'
import json, os
path = os.path.expanduser("~/.anet/ids/provider/config.json")
config = json.load(open(path))
config["inbound"]["public_capabilities"] = [{"id": "text.digest"}]
config.setdefault("modules", {})["service"] = {
    "capabilities": [{
        "id": "text.digest",
        "url": "unix://" + os.path.expanduser("~/.anet-tutorial/digest.sock") + ":/digest",
        "price": 2,
        "description": "SHA-256 digest of a text",
    }]
}
json.dump(config, open(path, "w"), indent=2)
EOF
$ anet stop provider
$ anet up provider

anet doctor 确认服务可达且该能力为公开：

$ anet --id provider doctor | grep -E 'inbound|backend'
[ok] inbound  policy closed; allow 0, trust 0, deny 0; public capabilities 1
[ok] backends.peer_check  service capability text.digest: the account listening on /home/user/.anet-tutorial/digest.sock is checked on every connection
[ok] backend.transport  service capability text.digest: socket /home/user/.anet-tutorial/digest.sock (owner uid 1000) passes the path checks; the listener is checked on each connection

入站策略仍为 closed。该策略管辖来自名单之外的对端的自由格式任务；对这些对端，节点提供的只有该公开能力。

查找能力并读取其卡片

请求方列出 Hub 上的 Agent。如果给出了查询文本，则在请求方节点上匹配。

$ anet --id requester find
name               charge  key        skills       AID
tutorial-provider  paid    confirmed  text.digest  <provider-aid>

charge 列的取值为 free、partial 或 paid，由公开卡片上的 a2a-x402 声明得出，无需联系提供方。key 显示 Hub 是否已确认该 Agent 的当前密钥。

anet card 显示带价格的卡片。价格由提供方签名，请求方节点端到端取得，因此 Hub 从不持有价格。

$ anet --id requester card "$PROVIDER"
tutorial-provider  <provider-aid> (verified, key confirmed)  paid
  text.digest  2 credits
Prices are signed by the other side, fetched 10-16 03:35; payment follows the quote in the task, and a quote above these prices is not paid automatically.

调用能力并确认首次支付

请求方发送调用。收费能力以报价而非结果应答，而新节点不会自动支付任何款项，因此调用停在报价处：

$ TASK=$(anet --id requester delegate "$PROVIDER" --capability text.digest \
    --args '{"text":"hello"}' | sed -n 's/^  "id": "\(.*\)",$/\1/p')
$ anet --id requester task get "$TASK"
{
  "id": "ix_9508cc71c260d7da6b6dd493334f77d0",
  ...
  "metadata": {
    ...
    "anet.payment_note": "Quoted 2 credits; automatic payment is off (limit 0), so nothing was paid; run anet pay ix_9508cc71c260d7da6b6dd493334f77d0.",
    "anet.reason": "needs_operator_approval",
    ...
    "x402.payment.status": "payment-required"
  },
  "status": {
    ...
    "state": "TASK_STATE_INPUT_REQUIRED",
    ...
  }
}
payment: Quoted 2 credits; automatic payment is off (limit 0), so nothing was paid; run anet pay ix_9508cc71c260d7da6b6dd493334f77d0.
  → anet pay ix_9508cc71c260d7da6b6dd493334f77d0

该任务是 A2A 任务，处于 input-required 状态，元数据 x402.payment.status 为 payment-required，与 a2a-x402 扩展的规定一致。原因 needs_operator_approval 表示该决定属于运维者。payment 行说明所报的价格、适用的限额和下一条命令。

anet pay 即确认操作。它在终端上运行，输出报价以及适用于已确认支付的限额，仅在回答 yes 之后才签署授权：

$ anet --id requester pay "$TASK"
Quoted 2 credits, to <provider-aid> (tutorial-provider), for text.digest.
The price the other side signed is 2 credits.
Manual limit: ≤10 per payment, 50 left today.
Type yes to confirm: yes
{
  "task_id": "ix_9508cc71c260d7da6b6dd493334f77d0",
  "state": "working",
  "pay_state": "submitted",
  "x402.payment.status": "payment-submitted",
  "authorization_id": "bafyrei...",
  "note": "Paid 2 credits (you confirmed it in the terminal; 48 left today)."
}

授权仅对该任务有效。提供方检查收款方、金额、与任务的绑定以及有效期，请求 Hub 结算，并在结算之后执行该能力。通过 MCP 或本地 A2A 接口行事的 Agent 无法代运维者确认支付：它们的支付受 agent_max 和 agent_daily_max 限制，二者初始值均为 0。

超过提供方签名卡片上价格的报价绝不会被自动支付，任务中的语句会说明差额。

对已知的提供方允许自动支付

自动支付需要两项设置，均在终端上进行，且都要求确认：

• 将提供方加入收款方列表，并且

• 将单笔自动支付的限额 auto_max 提高到 0 以上。

$ anet --id requester payees add "$PROVIDER"
Add tutorial-provider (<provider-aid>) to the payee list: automatic payments (≤0 each) and agent payments (≤0 each, ≤0 a day) can go to it.
Type yes to confirm: yes
$ anet --id requester payments set auto_max=5
Change this node's payment limits:
  auto_max  0 → 5
Type yes to confirm: yes

每项更改都记录在节点的证据链中。anet payments 输出各项限额和当日已花费的金额。

下一次调用无需进一步输入即可支付：

$ TASK=$(anet --id requester delegate "$PROVIDER" --capability text.digest \
    --args '{"text":"hello"}' | sed -n 's/^  "id": "\(.*\)",$/\1/p')
$ anet --id requester task get "$TASK" | tail -1
payment: Quoted 2 credits, within your automatic limit (≤5 per payment, 46 left today): paid automatically.

任务需要数秒完成报价、结算和执行。如果 task get 显示状态 TASK_STATE_WORKING，请重复执行。

检查结果并验证回执

anet task get 输出完整的任务。结果是名为 anet.result 的产物，支付信息位于元数据中。

$ anet --id requester task get "$TASK"
{
  "id": "ix_6def456a4a11d91de62b182d92ef3e6f",
  "artifacts": [
    {
      "artifactId": "anet.result",
      "name": "text.digest",
      "parts": [
        {
          "data": {
            "capability": "text.digest",
            "evidence": {
              "observed_state": "{\"sha256\": \"2cf24dba5fb0a30e26e83b2ac5b9e29e1b161e5c1fa7425e73043362938b9824\", \"bytes\": 5}",
              "protocol": "http",
              "verify_trust": 1,
              ...
            },
            "paid": {
              "amount": "2",
              "network": "hub:<hub-aid>",
              "receipt": "ogGmAXg7...",
              "transaction": "bafyrei..."
            },
            "status": "OK",
            "verifiable": true
          },
          "mediaType": "application/json"
        }
      ]
    }
  ],
  ...
  "metadata": {
    "anet.effect_status": "OK",
    "anet.payment_note": "Quoted 2 credits, within your automatic limit (≤5 per payment, 46 left today): paid automatically.",
    "anet.receipt_verified": "verified",
    "x402.payment.status": "payment-completed",
    ...
  },
  "status": { "state": "TASK_STATE_COMPLETED", ... }
}

三个字段说明了发生的情况：

evidence.observed_state

服务的应答。verify_trust: 1 仅记录服务已应答，别无其他含义。节点无法确认应答是否正确，除非服务自身返回 evidence 对象，否则提供方的任何配置都不能声明更多。

anet.receipt_verified

结果附有提供方签名的回执。请求方的节点仅在回执与请求、结果及双方身份相符之后才接受结果。

x402.payment.receipts

由 Hub 签名的结算回执。节点仅在检查授权属于该任务、收款方为该提供方且金额相符之后，才将该支付记录为已结算。

anet verify 可日后根据存储的数据重复回执检查：

$ anet --id requester verify "$TASK"
✓ signature verifies under <provider-aid>
  interaction  ix_6def456a4a11d91de62b182d92ef3e6f
  requester    <requester-aid>
  request cid  bafyrei...
  result cid   bafyrei...
  completed    2026-10-16T03:32:27Z
  receipt cid  bafyrei...

✓ and it covers exactly the result bytes checked.
✓ and it answers exactly the request checked.

给定回执和提供方的密钥历史（即任务元数据中的字段 anet.receipt.receipt 与 anet.receipt.provider_kel），在另一台没有守护进程、Hub 或网络的机器上也能进行同样的检查：

$ anet --id requester task get "$TASK" > task.json
$ RECEIPT=$(python3 -c 'import json; print(json.load(open("task.json"))["metadata"]["anet.receipt"]["receipt"])')
$ PROVIDER_KEL=$(python3 -c 'import json; print(json.load(open("task.json"))["metadata"]["anet.receipt"]["provider_kel"])')
$ anet verify --receipt "$RECEIPT" --kel "$PROVIDER_KEL"
✓ signature verifies under <provider-aid>
  ...
  note: the content was not checked — pass --result FILE to bind
        this receipt to the bytes it claims to cover.

读取送达状态

已签名的结果表明提供方生成了它，送达状态则表明消息是否到达了对方节点。节点发出的每条消息处于三种状态之一：

anet.delivery	含义
pending	消息在途。anet.delivery_detail 说明其所在位置：not_sent（节点无法连接 Hub，将重试）、sent（已交给 Hub，尚未确认）或 queued_at_hub（存放于 Hub，等待对方节点取走）。
confirmed	对方节点已打开并确认了消息。语句为：“Delivered: the other side's node confirmed it.”
unconfirmed	节点已停止等待。详情为 not_sent 时，消息从未离开本节点；详情为 sent 时，消息仍可能已经到达。

确认由接收节点生成。Hub 将消息的状态保留 7 天，发送方使用随机标识符查询。消息处于待定状态时，语句末尾会给出若消息仍未送达则任务失败的时间。该时间取以下两个时刻中较早者：消息交出之后经过 no_response_after（默认 15 分钟），以及 14 天的消息存活期结束。

如果在限期内未确认送达，任务以原因码 delivery_unconfirmed 失败，节点会请求对方取消，使发送方已放弃的请求不会在对方节点上线后被执行。语句会说明所适用的变体，例如 “Delivery was not confirmed within <limit>: it is still waiting at the hub (the other side may be offline), and anet asked them to cancel it; send it again later if you still need it.”全部变体见 原因码 参考。

该状态是命令行、MCP 工具 get_task 与 wait_task 以及本地 A2A 接口中任务投影的一部分。已进入最终状态的任务不再带有收尾语句。

查看支出

以下三条命令显示请求方一侧的情况：

$ anet --id requester payments
{
  "auto_max": 5,
  "agent_max": 0,
  "agent_daily_max": 0,
  "explicit_max": 10,
  "daily_max": 50,
  "spent_today": 4,
  "agent_spent_today": 0,
  "left_today": 46,
  "agent_left_today": 0,
  "payees": 1
}
$ anet --id requester balance
{
  "asset": "credit",
  "balance": 16,
  "entries": [
    { "delta": 20, "reason": "admission grant", ... },
    { "delta": -2, "reason": "bafyrei...", ... },
    { "delta": -2, "reason": "bafyrei...", ... }
  ],
  ...
}

每日合计按已签名的授权计算，而不是按已结算的金额。在账本条目中，支付的原因是其授权的标识符。

提供方的余额增加了相同的金额：

$ anet --id provider balance | grep '"balance"'
  "balance": 4,

证据链记录每一步，并由执行该步骤的节点签名。过滤选项 --type 用于选择事件类型：

$ anet --id requester audit --type anet.payment.settled
Evidence chain did:anet:<requester-aid>
  ...
Events — source: records this node signed; [brackets] say where each recorded fact came from
  #11    2026-10-16T03:32:27Z  payment settled (paid)  hub receipt: verified  amount=2 auth_id=bafyrei... interaction_id=ix_6def... network=hub:<hub-aid> payee=<provider-aid> transaction=bafyrei...  [hub receipt, checked by this node]

Summary — source: counted here from the events listed (1 events)
  payments settled   1: paid with hub receipt verified 1, could not verify 0; received (hub response) 0
  policy changes     0

anet audit --export DIR 将整条链连同密钥历史一并写出，anet verify --chain DIR 可在其他位置检查它。对账命令 anet reconcile 和 anet audit-hub 将节点的支付记录和余额证明与 Hub 的账本和发放链进行比对，详见 付款（x402）。

清理

使用 Ctrl-C 停止示例服务。停止两个节点并移除它们的身份，同时会删除其数据目录：

$ anet stop provider
$ anet stop requester
$ anet id rm provider --purge
$ anet id rm requester --purge

后续步骤

• 示例 展示受限能力、速率限制、服务中的调用方信息，以及名单内对端之间的任务交换。

• 能力与 Agent 卡片 与 付款（x402） 对卡片、价格和结算作完整说明。

• 接入编码 Agent 将编程 Agent 连接到节点，使 Agent 通过 MCP 执行本教程的各个步骤。Claude Code、Codex、Cursor、WorkBuddy、Hermes Agent、opencode 及其他客户端的指南，请从 接入 AI 工具 开始。