---
type: study
created: 2026-08-11
updated: 2026-08-11
sensitivity: standard
status: verified
tags:
  - study
  - langchain
  - langsmith
  - agent-server
  - cron
  - scheduling
topic: LangSmith Agent Server Crons API
sources:
  - https://docs.langchain.com/langsmith/agent-server-api/crons
  - https://docs.langchain.com/langsmith/agent-server-api/crons/count-crons
  - https://docs.langchain.com/langsmith/agent-server-api/crons/create-cron
  - https://docs.langchain.com/langsmith/agent-server-api/crons/create-thread-cron
  - https://docs.langchain.com/langsmith/agent-server-api/crons/delete-cron
  - https://docs.langchain.com/langsmith/agent-server-api/crons/get-cron
  - https://docs.langchain.com/langsmith/agent-server-api/crons/search-crons
  - https://docs.langchain.com/langsmith/agent-server-api/crons/update-cron
last_verified: 2026-08-11
---

# Crons：调度、保留与并发

Cron 是周期性 Run。无 Thread 的 Cron 每次在隔离 Thread 中执行；Thread Cron 复用指定 Thread，从而累积 state，但也必须处理同一 Thread 的并发。

## 八个路由

| 能力 | 方法与路径 | 说明 |
|---|---|---|
| 创建隔离 Cron | `POST /runs/crons` | 新执行各用独立 Thread；根文档是 Thread Cron 创建入口，需注意两个入口含义不同 |
| 创建 Thread Cron | `POST /threads/{thread_id}/runs/crons` | 固定在一个 Thread 上运行 |
| 读取/删除 | `GET`、`DELETE /runs/crons/{cron_id}` | 不存在 404 |
| Patch | `PATCH /runs/crons/{cron_id}` | 更新调度与 Run payload |
| 搜索 | `POST /runs/crons/search` | assistant/thread/enabled/metadata 过滤，分页排序与字段选择 |
| 计数 | `POST /runs/crons/count` | assistant/thread/metadata 过滤 |

## 创建契约

两类创建都必填 `schedule` 和 `assistant_id`（可使用 Assistant UUID 或 graph 名）。共同可选：

- IANA `timezone`；为空按 UTC；
- ISO date-time `end_time`；
- input、metadata、config、runtime context、webhook；
- interrupt before/after；
- enabled（默认 true）；
- stream mode/subgraphs/resumable；
- durability（sync/async/exit，默认 async）。

隔离 Cron 用 `on_run_completed` 控制每次临时 Thread：`delete` 默认清理，`keep` 为每次执行保留新 Thread。Thread Cron 则用 `multitask_strategy`（reject/rollback/interrupt/enqueue，默认 enqueue）处理重叠执行。

返回 `Cron` 包含 cron/assistant/thread IDs、schedule、end/next run 时间、payload、metadata、enabled 与创建更新时间。

## 搜索与运维

搜索默认 limit 10、offset 0，可按 cron/assistant/thread ID、next run/end/created/updated 时间排序；默认 created_at desc。`select` 可只返回需要字段。`enabled=false` 是暂停，不会删除；Patch 调度或时区后应读取 `next_run_date` 验证。

## 生产设计

- cron expression 与时区作为一对配置审计；DST 切换、月末和闰日必须有测试。
- 创建前生成稳定业务 ID/metadata，重复请求先搜索；API 没有显式幂等键时由调用方防重。
- Thread Cron 的任务必须幂等。`enqueue` 可能堆积，`interrupt`/`rollback` 可能留下外部副作用，`reject` 会漏执行；按业务语义选择并监控。
- `keep` 会持续增长 Thread 与 checkpoint，配套 TTL/归档；`delete` 前确认 Trace 与结果已交付。
- disabled、end_time、删除分别表示暂停、自然终止、移除调度；控制台要明确区分。
- webhook、外部工具和定时输入都遵循最小权限；敏感任务加入审批或把高风险副作用拆到受控服务。