mcpField
C
crontap-recurring-agent-endpoint

crontap-recurring-agent-endpoint

github.com/crontap云与 DevOps1935 次安装6 周前更新
代码仓库

关于 crontap-recurring-agent-endpoint

crontap-recurring-agent-endpoint 是将 Crontap 与应用自有 HTTP 服务、队列和 Agent Worker 结合的部署指南，面向已运行此类服务的用户。它说明如何安排请求并通过心跳核验任务完成，而非唤醒 MCP 客户端或 IDE 会话。

主要功能

  1. 01调度受保护的 HTTP 端点
  2. 02通过心跳监测任务完成
  3. 03说明端点认证与幂等要求
  4. 04核验队列、Worker 和心跳证据
  5. 05区分应用调度与客户端自动化

适用场景

  1. 01定时将任务加入应用队列
  2. 02监测 Agent Worker 是否完成周期任务
  3. 03排查请求已调度但心跳缺失

MCP 相关

该技能使用 Crontap MCP 创建调度和心跳并检查记录。它明确指出 MCP 服务端不会主动联系客户端，Crontap 也不会唤醒 Agent、IDE 会话或聊天。

安装

复制下面的命令，在终端中运行。

$npx skills add https://github.com/crontap/skills --skill crontap-recurring-agent-endpoint

安装后在 Claude Code 中输入/crontap-recurring-agent-endpoint确认已加载。

详细介绍

安排应用自有的 Agent 端点

仅当用户控制着一个已部署、负责启动工作流的 HTTP 服务时，才使用此架构。Crontap 会安排 HTTP 请求并监控签到。它不会唤醒 Agent、IDE 会话、聊天或 MCP 客户端。

如果要在 Cursor、Claude、ChatGPT、Codex 或其他客户端中设置定期提示词，请使用该客户端的原生自动化功能。MCP 客户端会发起工具调用；MCP 服务不会主动联系它们。

架构

Crontap clock -> protected app endpoint -> app-owned queue -> agent worker
                                                     |
                                                     +-> heartbeat on completion

前提条件

使用必需的工具前，请先检查这些工具是否可用。如果缺少任何工具，请停止操作，并向用户提供且仅提供以下两个选项：

  1. 连接 Crontap MCP，地址为 https://mcp.crontap.com/mcp。所有 Crontap 套餐均支持 MCP 访问。
  2. 为原始 API 配置 $CRONTAP_CLIENT_ID 和 $CRONTAP_API_KEY。原始 API 访问需要 Ultra 套餐。

在用户选择之前，请勿自行选择路径或继续操作。

  • 已存在已部署的应用端点和持久化工作进程。
  • 端点使用专用的 cron 密钥进行身份验证。
  • 入队和下游影响均按逻辑运行周期实现幂等。
  • 工作进程能够安全读取心跳 URL。

工作流

  1. 创建心跳，并设置与预期完成时间相匹配的周期和宽限时间。
  2. 将其密钥 URL 存储在工作进程的密钥管理器中。
  3. 更新工作进程，使其仅在成功持久化完成后发送 ping，并在明确的终止失败时使用 /fail。
  4. 为受保护的入队端点创建 Crontap 计划。
  5. 验证入队证据、工作进程证据和心跳证据。

MCP 示例

创建完成情况监控：

{
  "tool": "create_heartbeat",
  "arguments": {
    "name": "Daily agent workflow completion",
    "periodMinutes": 1440,
    "graceMinutes": 60
  }
}

创建 HTTP 时钟：

{
  "tool": "create_schedule",
  "arguments": {
    "url": "https://agent-app.example.com/api/jobs/daily-analysis",
    "text": "every day at 07:00",
    "timezone": "UTC",
    "method": "POST",
    "headers": {
      "Authorization": "Bearer <cron-secret-from-secure-store>",
      "Content-Type": "application/json"
    },
    "body": {
      "workflow": "daily-analysis"
    },
    "label": "Daily analysis enqueue"
  }
}

检查某个 UTC 日期的心跳证据：

{
  "tool": "get_heartbeat_pings",
  "arguments": {
    "heartbeatId": "<heartbeat-id>",
    "day": "2026-09-14"
  }
}

端点约定

  • 在读取请求正文或入队之前进行身份验证。
  • 派生或接收稳定的逻辑运行键，并通过持久化方式确保其唯一性。
  • 仅在队列已接受任务后返回 2xx。
  • 仅在可以安全地再次尝试入队时返回可重试的 5xx。
  • 将模型提供商凭据保留在工作进程环境中。

REST 回退方案

创建 REST 资源需要 Ultra API 访问权限：

curl --fail-with-body https://api.crontap.com/v1/schedule \
  -X POST \
  -H "ClientId: $CRONTAP_CLIENT_ID" \
  -H "ApiKey: $CRONTAP_API_KEY" \
  -H "Content-Type: application/json" \
  --data '{
    "url": "https://agent-app.example.com/api/jobs/daily-analysis",
    "interval": "0 7 * * *",
    "timezone": "UTC",
    "verb": "POST",
    "headers": {
      "Authorization": "Bearer <cron-secret-from-secure-store>",
      "Content-Type": "application/json"
    },
    "data": {"workflow": "daily-analysis"},
    "label": "Daily analysis enqueue"
  }'

连接后请使用 MCP。MCP 访问并非 Ultra 专属。

验证

  • 一次计划调用会为该逻辑周期创建一条持久化队列记录。
  • 工作进程重试不会导致外部副作用重复。
  • 成功 ping 发生在持久化完成之后，而不只是入队之后。
  • 缺失或失败的运行会显示在心跳历史记录中，且不会暴露密钥 URL。

安全与套餐限制

  • 切勿在提示词或日志中暴露模型密钥、cron 密钥或心跳 URL。
  • 在应用自有的工作进程中限制成本、运行时间、模型调用次数和外部写入操作。
  • 没有已部署端点时，请使用客户端原生自动化。
  • 如果资源限制阻止了创建操作，请保留返回的四选项阶梯，并指出最小的可行选项。

故障排查

  • 计划成功但没有心跳，意味着入队成功，但工作进程未完成任务或未发送 ping。
  • 计划失败，意味着应先排查 HTTP 边界，再排查工作进程。
  • 队列记录重复，意味着入队端点缺少原子幂等性。
  • 待处理状态的心跳尚未收到第一个已接受的 ping。

参考资料

评论

支持 Markdown