A2H: ask a human

a2h-gateway

适用于 A2H 的可自托管网关。A2H 是 Agent-to-Human 协议：AI Agent 和脚本向人员请求批准或信息，人员通过电子邮件、Telegram 或推送通知作答，Agent 随后会收到附有签名、可证明决策者身份的答复。它是一个使用 SQLite 的独立 Go 二进制文件。

$ a2h ask -to mailto:[email protected] -why "Rolls back if health checks fail." "Deploy v2.3 to production?"
Waiting for an answer from mailto:[email protected] (interaction 01a1bbcf-…)…
Approved (email_link.v1) at 2026-11-08T15:37:50Z.
$ echo $?
0

Twilio Labs 于 2026 年 2 月发布了 A2H，并提供了规范、OpenAPI 模式和概念验证演示。其路线图将参考网关和正式 JSON Schema 列为下一步。本项目是这两者的独立实现，与 Twilio 无关。

功能

• 完整的面向 Agent 的 A2H 1.0 API：发现（/.well-known/a2h）、POST /v1/intent、状态、取消、nonce、JWKS。
• **支持所有意图：**AUTHORIZE（批准或拒绝）、COLLECT（包含文本、选项、数字和日期的表单，并进行验证）、INFORM、RESULT、ESCALATE。
• **通知渠道：**电子邮件（SMTP）、Telegram 机器人、通过 ntfy 推送（可自托管或使用 ntfy.sh），以及用于开发的控制台渠道。支持按规范中的退避策略重试，并支持备用渠道。
• 决策证明：
  • 每个 RESPONSE 都经过签名（基于 JCS 的 ES256 分离式 JWS，密钥存储在 JWKS 中）；
  • assurance.level: HIGH 的请求必须通过通行密钥（WebAuthn）批准，质询会按第 1.11.4 节的要求绑定到交互。
• 重放保护：
  • 基于 message_id 的幂等性；
  • 时间戳有效期和一次性 nonce；
  • 与交互同时过期、不可猜测且只能使用一次的链接。
• Webhook 使用 HMAC 签名（X-A2H-Signature），按 10 秒 / 60 秒 / 5 分钟的间隔重试，并支持轮询作为备用方式。
• JSON Schema：为每种 A2H 消息提供模式，位于 schemas/。
• MCP 服务（a2h mcp）：Claude、Cursor 和其他 MCP 客户端中的 Agent 可将此服务用作工具来请求你批准。
• 一致性测试套件，用于测试任意 A2H 网关：a2h conform。

快速开始

从发布页面下载适用于 Linux、macOS、Windows 或 FreeBSD 的二进制文件，使用 Docker 镜像 ghcr.io/andreaacanfora/a2h-gateway，或使用 Go 安装：

go install github.com/AndreaAcanfora/a2h-gateway/cmd/a2h@latest

# Development: no authentication, links printed in the log.
A2H_BASE_URL=http://localhost:8080 A2H_DEV=1 a2h serve

在另一个终端中：

A2H_GATEWAY=http://localhost:8080 a2h ask -to console:me "Delete 3 unused files?"

网关会在日志中输出一个链接（url=http://localhost:8080/i/…）：打开链接并批准后，a2h ask 将以 0 退出。

用于生产环境

docker run -d -p 8080:8080 -v a2h-data:/data \
  -e A2H_BASE_URL=https://a2h.example.com \
  -e A2H_API_KEYS="deploy-bot:$(openssl rand -hex 24)" \
  -e SMTP_HOST=smtp.example.com -e [email protected] -e SMTP_PASSWORD=… \
  -e TELEGRAM_BOT_TOKEN=123456:ABC… \
  -e A2H_PUSH=1 \
  ghcr.io/andreaacanfora/a2h-gateway

将其部署在 HTTPS 后面：人员需要打开它生成的链接，而通行密钥只有在安全源上才能使用。

**Telegram：**使用 @BotFather 创建机器人，然后向机器人发送任意消息，以便它能向你发送消息。你的聊天 ID 位于 https://api.telegram.org/bot<token>/getUpdates 中（message.chat.id）。当 A2H_BASE_URL 是公开主机名时，消息会显示操作按钮；如果使用 localhost，链接会显示在文本中，因为 Telegram 不允许此类按钮。

变量	含义
A2H_BASE_URL	人员打开的公开 URL（必填）
A2H_LISTEN	监听地址，默认为 :8080
A2H_DATA_DIR	数据库、签名密钥和链接密钥，默认为 ./a2h-data
A2H_API_KEYS	以逗号分隔的 name:key 键值对；Agent 发送 X-A2H-API-Key
SMTP_HOST、SMTP_PORT、SMTP_USERNAME、SMTP_PASSWORD、SMTP_FROM	电子邮件渠道（STARTTLS 或 TLS）
TELEGRAM_BOT_TOKEN	Telegram 渠道；地址格式为 tg:<chat_id>（见下文）
A2H_PUSH、NTFY_TOKEN	推送渠道（ntfy）；地址为主题 URL
A2H_CONSOLE	控制台渠道（链接显示在日志中）
A2H_DEV	开发模式：不进行身份验证，允许使用 http:// Webhook，并启用控制台。切勿将其暴露给外部。

通过 Agent 发起请求

任何 HTTP 客户端都可以使用：

curl -s https://a2h.example.com/v1/intent -H "X-A2H-API-Key: $KEY" -H 'content-type: application/json' -d '{
  "type": "AUTHORIZE",
  "message_id": "'$(uuidgen)'",
  "agent_id": "did:web:booking-agent.example.com",
  "principal_id": "usr_alice",
  "channel": { "type": "email", "address": "mailto:[email protected]",
               "fallback": [{ "type": "push", "address": "https://ntfy.sh/alice-a2h-7f3k" }] },
  "render": { "title": "Book flight?", "body": "Book the non-refundable flight to Lisbon for 412 EUR?" },
  "explanation_bundle": { "why": "The fare expires in 30 minutes." },
  "ttl_sec": 1800,
  "callback": { "url": "https://agent.example.com/a2h/webhook", "secret": "whsec_…" }
}'

随后等待 Webhook，或轮询 GET /v1/status/{interaction_id}，直到状态变为 ANSWERED、EXPIRED、CANCELLED 或 FAILED。

在 Go 中，a2h 包会完成所有这些操作并验证答复：

c := a2h.NewClient("https://a2h.example.com", key)
sent, _ := c.Send(ctx, msg)
status, _ := c.Wait(ctx, sent.InteractionID, 2*time.Second)
resp, err := c.VerifyResponse(ctx, status.Response, msg.MessageID) // checks responds_to and the JWS
if err == nil && resp.Decision == a2h.Approve { /* go ahead */ }

在 AI Agent 中使用（MCP）

a2h mcp 是一个 Model Context Protocol 服务：Claude Code、Claude Desktop、Cursor 和其他 MCP 客户端可以使用其中的工具， 在采取行动前征求你的意见。

工具	功能
request_approval	请求你批准或拒绝某项操作；返回经过验证的决定
ask_human	请你填写一份简短表单（文本、数字、日期、选项、是/否）
notify_human	向你发送消息（进度、结果、提醒）
check_request	跟进仍在等待处理的请求
cancel_request	撤回尚未得到答复的请求

它已作为 io.github.AndreaAcanfora/a2h-gateway 列入 官方 MCP Registry，因此可以浏览注册表的 MCP 客户端能够安装它；也可以手动配置。

Claude Code：

claude mcp add a2h \
  -e A2H_GATEWAY=https://a2h.example.com -e A2H_API_KEY=… -e A2H_TO=tg:123456789 \
  -- a2h mcp

Claude Desktop（claude_desktop_config.json）、Cursor 等：

{
  "mcpServers": {
    "a2h": {
      "command": "a2h",
      "args": ["mcp"],
      "env": { "A2H_GATEWAY": "https://a2h.example.com", "A2H_API_KEY": "…", "A2H_TO": "mailto:[email protected]" }
    }
  }
}

然后告诉 Agent 何时应该征求意见，例如：“删除任何内容或花钱之前，先用 request_approval 征求我的批准”。

• 接收方由配置决定。 模型可以撰写问题，但无法选择发送对象，因此 Agent 不能给其他人发消息。
• 答案会经过验证：工具报告决定前，会根据网关的签名验证答案。验证失败的答案会报告为失败，绝不会被视为批准。
• 长时间等待： 工具调用最多等待 10 分钟（-max-wait），期间会发送进度通知。如果对方届时尚未答复，工具会说明这一点，Agent 随后使用 check_request 继续跟进。
• 高风险事项： 设置 require_passkey: true 后，批准必须使用通行密钥。

高风险审批的通行密钥

带有 "assurance": {"level": "HIGH"} 的请求（或 required_factors 包含 passkey.webauthn.v1 的请求）不能通过点击批准：对方必须使用通行密钥确认（Face ID、Touch ID、Windows Hello 或安全密钥）。只有操作员可以在服务上注册通行密钥：

a2h enroll -principal usr_alice
# Send this link to usr_alice. It works once and expires in 24h0m0s:
# https://a2h.example.com/enroll/…

RESPONSE 随后会携带 WebAuthn 断言、质询随机数和公钥，因此 Agent 可以自行验证对方的签名。

一致性

a2h conform -gateway https://gateway.example.com -key $KEY -to mailto:[email protected]

PASS  MUST   §1.4      discovery document
PASS  MUST   §1.3      RESPONSE type from an agent is rejected
PASS  MUST   §1.5      unsupported profile is rejected
PASS  MUST   §1.10.2   duplicate message_id returns the original interaction
PASS  MUST   §1.7      cancel a waiting interaction
…
conforming to the agent-facing API of A2H 1.0

测试套件会向你提供的地址发送实际意图，然后将其取消。

规范中不明确的部分

A2H 1.0 有些细节尚未明确，或以两种方式描述。此处采用的选择列在 docs/implementation-notes.md 中，作为对下一版规范的反馈。

开发

go test -race ./...                        # unit and integration tests
go build -o e2e/a2h ./cmd/a2h && (cd e2e && npm install && npm test)   # passkeys in Chromium

许可证

MIT。A2H 由 Twilio Labs 版权所有，采用 MIT 许可证。