crontap-recurring-agent-endpoint

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

Schedule an app-owned agent endpoint

调度应用自有的 Agent 端点

Use this architecture only when the user controls a deployed HTTP service that starts the workflow. Crontap schedules the HTTP request and monitors check-ins. It does not wake agents, IDE sessions, chats, or MCP clients.

For a recurring prompt inside Cursor, Claude, ChatGPT, Codex, or another client, use that client's native automation feature. MCP clients initiate tool calls; an MCP server does not initiate contact with them.

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

对于 Cursor、Claude、ChatGPT、Codex 或其他客户端中的周期性提示，请使用相应客户端的原生自动化功能。MCP 客户端会发起 tool call；MCP server 不会主动联系它们。

Architecture

架构

text

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

text

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

Prerequisites

前置条件

Before using the required tools, check whether they are available. If any are missing, stop and offer the user exactly two choices:

Connect Crontap MCP at
```
https://mcp.crontap.com/mcp
```
. MCP access works on every Crontap tier.
Configure
```
$CRONTAP_CLIENT_ID
```
and
```
$CRONTAP_API_KEY
```
for the raw API. Raw API access requires Ultra.

Do not silently choose a path or continue until the user selects one.

A deployed application endpoint and durable worker already exist.
The endpoint authenticates a dedicated cron secret.
Enqueueing and downstream effects are idempotent by logical run period.
The worker can securely read a heartbeat URL.

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

在
```
https://mcp.crontap.com/mcp
```
连接 Crontap MCP。所有 Crontap 套餐都支持 MCP 访问。
配置
```
$CRONTAP_CLIENT_ID
```
和
```
$CRONTAP_API_KEY
```
以使用 raw API。Raw API 访问需要 Ultra 套餐。

在用户选定一种方式之前，不得擅自选择路径或继续操作。

已部署的应用端点和应用自有的持久化 worker 已经存在。
端点会验证专用的 cron secret。
对于同一逻辑运行周期，入队及下游操作具备幂等性。
worker 能够安全读取 heartbeat URL。

Workflow

工作流

Create a heartbeat with a period and grace matching expected completion.
Store its secret URL in the worker's secret manager.
Update the worker to ping only after durable successful completion and use
```
/fail
```
for explicit terminal failure.
Create a Crontap schedule for the protected enqueue endpoint.
Verify enqueue evidence, worker evidence, and heartbeat evidence.

创建 heartbeat，并设置与预期完成时间匹配的 period 和 grace。
将其 secret URL 存储在 worker 的 secret manager 中。
更新应用自有的 worker，使其仅在任务已持久化且成功完成后执行 ping，并在发生明确的终止性失败时使用
```
/fail
```
。
为受保护的入队端点创建 Crontap schedule。
验证入队证据、worker 证据和 heartbeat 证据。

MCP examples

MCP 示例

Create completion monitoring:

json

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

Create the HTTP clock:

json

{
  "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"
  }
}

Inspect heartbeat evidence for one UTC day:

json

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

创建完成情况监控：

json

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

创建 HTTP 时钟：

json

{
  "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 日的 heartbeat 证据：

json

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

Endpoint contract

端点契约

Authenticate before reading the request body or enqueueing.
Derive or receive a stable logical-run key and enforce uniqueness durably.
Return 2xx only after the queue has accepted the job.
Return a retryable 5xx only when another enqueue attempt is safe.
Keep model provider credentials inside the worker environment.

在读取请求正文或执行入队之前完成身份验证。
派生或接收稳定的逻辑运行键，并以持久化方式实施唯一性约束。
仅在队列已经接受任务后返回 2xx。
仅当再次尝试入队是安全的，才返回可重试的 5xx。
将模型提供商凭据保留在 worker 环境中。

REST fallback

REST 备用方案

REST creation requires Ultra API access:

bash

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"
  }'

Use MCP when connected. MCP access is not Ultra-only.

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

bash

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 套餐。

Verification

验证

One schedule call creates one durable queue record for the logical period.
A worker retry does not duplicate external side effects.
Success pings happen after durable completion, not merely after enqueue.
A missing or failed run appears in heartbeat history without exposing the secret URL.

一次 schedule 调用会为一个逻辑周期创建一条持久化队列记录。
worker 重试不会重复产生外部副作用。
成功 ping 仅在任务持久化并成功完成后发生，而不能仅在入队后发生。
缺失或失败的运行会出现在 heartbeat 历史记录中，同时不会暴露 secret URL。

Safety and plan limits

安全与套餐限制

Never expose model keys, cron secrets, or heartbeat URLs in prompts or logs.
Bound cost, runtime, model calls, and external writes inside the app-owned worker.
Use native client automation when no deployed endpoint exists.
If a resource limit blocks creation, preserve the returned four-option ladder and identify the smallest viable option.

绝不要在提示词或日志中暴露模型密钥、cron secret 或 heartbeat URL。
在应用自有的 worker 中限制成本、运行时长、模型调用次数和外部写入。
如果不存在已部署的端点，请使用客户端原生自动化功能。
如果资源限制阻止创建，应保留返回的四级选项阶梯，并确定最小可行选项。

Troubleshooting

故障排查

Schedule success plus heartbeat silence means enqueue succeeded but the worker did not complete or did not ping.
Schedule failure means debug the HTTP boundary before the worker.
Repeated queue records mean the enqueue endpoint lacks atomic idempotency.
A pending heartbeat has not received its first accepted ping.

schedule 成功但 heartbeat 始终静默，说明入队成功，但 worker 未完成或未发送 ping。
schedule 失败时，应先调试 worker 之前的 HTTP 边界。
队列记录重复出现，说明入队端点缺少原子幂等性。
处于 pending 状态的 heartbeat 尚未收到第一个已接受的 ping。

crontap-recurring-agent-endpoint

Original

Translation

Schedule an app-owned agent endpoint

调度应用自有的 Agent 端点

Architecture

架构

Prerequisites

前置条件

Workflow

工作流

MCP examples

MCP 示例

Endpoint contract

端点契约

REST fallback

REST 备用方案

Verification

验证

Safety and plan limits

安全与套餐限制

Troubleshooting

故障排查

References

参考