连接外部事件

通过 HTTP 回调，可以在 CI 完成或外部状态发生变化时及时通知 Agent。本指南以“唤醒回调（Wake callback）”为例进行演示：外部事件到达时唤醒 Agent 检查外部状态，再由 Agent 自主判定工作项是否能够继续推进。

前置条件

正常运行中的 Agent，拥有一个被持续跟踪的目标，以及需要关注的外部对象（例如某个具体的 CI 构建）。
赋予该 Agent 对该外部数据源的只读检查权限，并在指引中明确成功与失败后的处理规则。
确保外部系统能够网络访问该回调 URL。Loopback 地址仅对本机有效；若是远程外部服务，需配置好经过批准的远程访问或隧道。
回调 URL 属于机密凭据。在操作过程中避免在 Shell 历史记录或详细 HTTP 日志中打印明文。
以下由操作者执行的示例依赖 curl、jq 以及宿主机上的控制平面访问权限。

操作步骤

获取 Agent 当前的默认接入凭据：

AGENT_ID=builder
TOKEN=$(jq -r .token ~/.holon/credentials.json 2>/dev/null || echo "$HOLON_CONTROL_TOKEN")

curl -s -H "Authorization: Bearer $TOKEN" \
  "http://127.0.0.1:7878/api/control/agents/$AGENT_ID/reset-callback" -X POST

该操作会吊销旧的默认凭据并返回包含新 trigger_url 的 JSON 响应。请妥善保存该 URL。

在外部系统中配置 Webhook：将获取到的 trigger_url 填入 CI 系统（如 GitHub Actions、GitLab CI）的 Webhook 通知配置中，设置为在构建结束时触发 HTTP POST。对于唤醒模式（wake_hint），空的 POST 请求体即可生效。
让 Agent 启动任务并登记等待：要求 Agent 触发构建并等待其结果。在底层，Agent 会记录工作项、触发外部构建，并执行如下等待调用：
```
{
  "wake": "external",
  "resource": "github:holon-run/holon#run/12345",
  "reason": "等待 GitHub Actions CI 构建 #12345 完成",
  "delivery": "final"
}
```
随后 Agent 进入挂起状态，让出当前轮次的执行权。
触发测试唤醒：在外部 CI 触发前，可手动发送一条空的 POST 请求模拟外部通知：
```
curl -X POST "$TRIGGER_URL"
```
验证唤醒与后续执行：观察守护进程状态与 Agent 日志：
```
holon agent get $AGENT_ID
holon transcript --agent $AGENT_ID --limit 10
```
应该能观察到 Agent 被该次外部事件唤醒，随后主动调用工具查询 CI 的真实状态，并根据查询到的结果继续推进。

确认配置成功

回调 URL 正确返回 200 OK 或受理状态。
处于挂起等待状态的工作项在收到通知后被正确唤醒。
Agent 没有盲目轻信 Webhook，而是主动核实了对应的外部构建记录与 Commit SHA。

凭据轮换与清理

当集成不再使用或凭据意外暴露时，应立即进行轮换或吊销：

# 重新重置并生成新凭据（旧凭据立即失效）
curl -s -H "Authorization: Bearer $TOKEN" \
  "http://127.0.0.1:7878/api/control/agents/$AGENT_ID/reset-callback" -X POST

停止 Agent 同样会自动吊销其绑定的外部触发器。

另见

事件、等待与唤醒概念 — 异步心智模型
事件与定时器参考 — 端点与字段契约
调度 Agent 工作 — 基于时间的定时调度