> ## Documentation Index
> Fetch the complete documentation index at: https://cndoc-langchain.site/llms.txt
> Use this file to discover all available pages before exploring further.

# 使用定时任务

在许多情况下，按计划运行助手非常有用。

例如，假设你正在构建一个每天运行并发送每日新闻摘要邮件的助手。你可以使用定时任务在每天晚上8:00运行该助手。

LangSmith 部署支持定时任务，这些任务按用户定义的计划运行。用户指定一个计划、一个助手和一些输入。之后，在指定的时间表上，服务器将：

* 使用指定的助手创建一个新线程
* 将指定的输入发送到该线程

请注意，每次都会向线程发送相同的输入。

LangSmith 部署 API 提供了多个用于创建和管理定时任务的端点。有关更多详细信息，请参阅 [API 参考](https://langchain-ai.github.io/langgraph/cloud/reference/api/api_ref/)。

有时你不想基于用户交互来运行你的图，而是希望按计划安排你的图运行——例如，如果你希望你的图每周编写并发送一封包含团队待办事项的电子邮件。LangSmith 部署允许你通过使用 `Crons` 客户端来实现这一点，而无需编写自己的脚本。要安排一个图任务，你需要传递一个 [cron 表达式](https://crontab.cronhub.io/) 来告知客户端你希望何时运行该图。`Cron` 任务在后台运行，不会干扰图的正常调用。

<Note>
  所有定时计划均按 **UTC** 时间解释。在指定计划时，请确保将所需的执行时间转换为 UTC。
</Note>

## 设置

首先，让我们设置我们的 SDK 客户端、助手和线程：

<Tabs>
  <Tab title="Python">
    ```python theme={"theme":{"light":"catppuccin-latte","dark":"catppuccin-mocha"}}
    from langgraph_sdk import get_client

    client = get_client(url=<DEPLOYMENT_URL>)
    # 使用部署名称为 "agent" 的图
    assistant_id = "agent"
    # 创建线程
    thread = await client.threads.create()
    print(thread)
    ```
  </Tab>

  <Tab title="Javascript">
    ```js theme={"theme":{"light":"catppuccin-latte","dark":"catppuccin-mocha"}}
    import { Client } from "@langchain/langgraph-sdk";

    const client = new Client({ apiUrl: <DEPLOYMENT_URL> });
    // 使用部署名称为 "agent" 的图
    const assistantId = "agent";
    // 创建线程
    const thread = await client.threads.create();
    console.log(thread);
    ```
  </Tab>

  <Tab title="CURL">
    ```bash theme={"theme":{"light":"catppuccin-latte","dark":"catppuccin-mocha"}}
    curl --request POST \
        --url <DEPLOYMENT_URL>/assistants/search \
        --header 'Content-Type: application/json' \
        --data '{
            "limit": 10,
            "offset": 0
        }' | jq -c 'map(select(.config == null or .config == {})) | .[0].graph_id' && \
    curl --request POST \
        --url <DEPLOYMENT_URL>/threads \
        --header 'Content-Type: application/json' \
        --data '{}'
    ```
  </Tab>
</Tabs>

输出：

```
{
'thread_id': '9dde5490-2b67-47c8-aa14-4bfec88af217',
'created_at': '2024-08-30T23:07:38.242730+00:00',
'updated_at': '2024-08-30T23:07:38.242730+00:00',
'metadata': {},
'status': 'idle',
'config': {},
'values': None
}
```

## 线程上的定时任务

要创建与特定线程关联的定时任务，你可以编写：

<Tabs>
  <Tab title="Python">
    ```python theme={"theme":{"light":"catppuccin-latte","dark":"catppuccin-mocha"}}
    # 这会安排一个任务在每天 UTC 15:27 (下午 3:27) 运行
    cron_job = await client.crons.create_for_thread(
        thread["thread_id"],
        assistant_id,
        schedule="27 15 * * *",
        input={"messages": [{"role": "user", "content": "What time is it?"}]},
    )
    ```
  </Tab>

  <Tab title="Javascript">
    ```js theme={"theme":{"light":"catppuccin-latte","dark":"catppuccin-mocha"}}
    // 这会安排一个任务在每天 UTC 15:27 (下午 3:27) 运行
    const cronJob = await client.crons.create_for_thread(
      thread["thread_id"],
      assistantId,
      {
        schedule: "27 15 * * *",
        input: { messages: [{ role: "user", content: "What time is it?" }] }
      }
    );
    ```
  </Tab>

  <Tab title="CURL">
    ```bash theme={"theme":{"light":"catppuccin-latte","dark":"catppuccin-mocha"}}
    curl --request POST \
        --url <DEPLOYMENT_URL>/threads/<THREAD_ID>/runs/crons \
        --header 'Content-Type: application/json' \
        --data '{
            "assistant_id": <ASSISTANT_ID>,
        }'
    ```
  </Tab>
</Tabs>

请注意，删除不再有用的 `Cron` 任务**非常重要**。否则，你可能会产生不必要的 LLM API 费用！你可以使用以下代码删除 `Cron` 任务：

<Tabs>
  <Tab title="Python">
    ```python theme={"theme":{"light":"catppuccin-latte","dark":"catppuccin-mocha"}}
    await client.crons.delete(cron_job["cron_id"])
    ```
  </Tab>

  <Tab title="Javascript">
    ```js theme={"theme":{"light":"catppuccin-latte","dark":"catppuccin-mocha"}}
    await client.crons.delete(cronJob["cron_id"]);
    ```
  </Tab>

  <Tab title="CURL">
    ```bash theme={"theme":{"light":"catppuccin-latte","dark":"catppuccin-mocha"}}
    curl --request DELETE \
        --url <DEPLOYMENT_URL>/runs/crons/<CRON_ID>
    ```
  </Tab>
</Tabs>

## 无状态定时任务

你也可以使用以下代码创建无状态定时任务。无状态定时任务为每次执行创建一个新线程：

<Tabs>
  <Tab title="Python">
    ```python theme={"theme":{"light":"catppuccin-latte","dark":"catppuccin-mocha"}}
    # 这会安排一个任务在每天 UTC 15:27 (下午 3:27) 运行
    cron_job_stateless = await client.crons.create(
        assistant_id,
        schedule="27 15 * * *",
        input={"messages": [{"role": "user", "content": "What time is it?"}]},
    )
    ```
  </Tab>

  <Tab title="Javascript">
    ```js theme={"theme":{"light":"catppuccin-latte","dark":"catppuccin-mocha"}}
    // 这会安排一个任务在每天 UTC 15:27 (下午 3:27) 运行
    const cronJobStateless = await client.crons.create(
      assistantId,
      {
        schedule: "27 15 * * *",
        input: { messages: [{ role: "user", content: "What time is it?" }] }
      }
    );
    ```
  </Tab>

  <Tab title="CURL">
    ```bash theme={"theme":{"light":"catppuccin-latte","dark":"catppuccin-mocha"}}
    curl --request POST \
        --url <DEPLOYMENT_URL>/runs/crons \
        --header 'Content-Type: application/json' \
        --data '{
            "assistant_id": <ASSISTANT_ID>,
        }'
    ```
  </Tab>
</Tabs>

再次提醒，完成后请记得删除你的任务！

<Tabs>
  <Tab title="Python">
    ```python theme={"theme":{"light":"catppuccin-latte","dark":"catppuccin-mocha"}}
    await client.crons.delete(cron_job_stateless["cron_id"])
    ```
  </Tab>

  <Tab title="Javascript">
    ```js theme={"theme":{"light":"catppuccin-latte","dark":"catppuccin-mocha"}}
    await client.crons.delete(cronJobStateless["cron_id"]);
    ```
  </Tab>

  <Tab title="CURL">
    ```bash theme={"theme":{"light":"catppuccin-latte","dark":"catppuccin-mocha"}}
    curl --request DELETE \
        --url <DEPLOYMENT_URL>/runs/crons/<CRON_ID>
    ```
  </Tab>
</Tabs>

## 无状态定时任务的线程清理

<Note>
  此功能需要 LangGraph API 版本 **0.5.18** 或更高版本，以及 Python SDK **0.3.2** 或更高版本，或 JavaScript SDK **1.4.0** 或更高版本。
</Note>

每次触发无状态定时任务时，都会创建一个新线程。使用 `on_run_completed` 参数控制运行完成后该线程的处理方式：

* **`"delete"`**（默认）：运行完成后自动删除线程。
* **`"keep"`**：保留线程以供后续检索。你需要负责清理这些线程。有关推荐方法，请参阅 [如何为你的应用添加 TTL](/langsmith/configure-ttl)。

### 示例：保留线程以供后续检索

<Tabs>
  <Tab title="Python">
    ```python theme={"theme":{"light":"catppuccin-latte","dark":"catppuccin-mocha"}}
    # 创建一个在执行后保留线程的无状态定时任务。
    # 在 langgraph.json 中配置 checkpointer.ttl 以自动删除旧线程。
    # 参见：https://docs.langchain.com/langsmith/configure-ttl
    cron_job = await client.crons.create(
        assistant_id,
        schedule="27 15 * * *",
        input={"messages": [{"role": "user", "content": "Daily report"}]},
        on_run_completed="keep"
    )

    # 你稍后可以检索运行及其结果
    runs = await client.runs.search(
        metadata={"cron_id": cron_job["cron_id"]}
    )
    ```
  </Tab>

  <Tab title="Javascript">
    ```js theme={"theme":{"light":"catppuccin-latte","dark":"catppuccin-mocha"}}
    // 创建一个在执行后保留线程的无状态定时任务。
    // 在 langgraph.json 中配置 checkpointer.ttl 以自动删除旧线程。
    // 参见：https://docs.langchain.com/langsmith/configure-ttl
    const cronJob = await client.crons.create(
      assistantId,
      {
        schedule: "27 15 * * *",
        input: { messages: [{ role: "user", content: "Daily report" }] },
        onRunCompleted: "keep"
      }
    );

    // 你稍后可以检索运行及其结果
    const runs = await client.runs.search({
      metadata: { cron_id: cronJob["cron_id"] }
    });
    ```
  </Tab>

  <Tab title="CURL">
    ```bash theme={"theme":{"light":"catppuccin-latte","dark":"catppuccin-mocha"}}
    # 创建一个在执行后保留线程的无状态定时任务。
    # 在 langgraph.json 中配置 checkpointer.ttl 以自动删除旧线程。
    # 参见：https://docs.langchain.com/langsmith/configure-ttl
    curl --request POST \
        --url <DEPLOYMENT_URL>/runs/crons \
        --header 'Content-Type: application/json' \
        --data '{
            "assistant_id": "<ASSISTANT_ID>",
            "schedule": "27 15 * * *",
            "input": {"messages": [{"role": "user", "content": "Daily report"}]},
            "on_run_completed": "keep"
        }'
    ```
  </Tab>
</Tabs>

***

<div className="source-links">
  <Callout icon="terminal-2">
    [将这些文档连接](/use-these-docs)到 Claude、VSCode 等，通过 MCP 获取实时答案。
  </Callout>

  <Callout icon="edit">
    [在 GitHub 上编辑此页面](https://github.com/langchain-ai/docs/edit/main/src/langsmith/cron-jobs.mdx) 或 [提交问题](https://github.com/langchain-ai/docs/issues/new/choose)。
  </Callout>
</div>