---
title: "长时间运行的 AI 智能体：超时、重试与检查点 | BroadRouter"
description: "让大模型智能体连续运行数小时：为每次调用设置超时、用流式输出发现卡顿、安全重试、让工具副作用幂等，并在每一步后保存检查点。"
url: https://broadrouter.com/zh/blog/long-running-agents-timeouts-retries/
lang: zh-Hans
updated: 2026-11-14
publisher: BroadRouter (a BroadNet site); API by BroadNet Inference, https://inference.broadnet.ai
---

本页由英文原文借助 AI 翻译。[阅读英文原文](https://broadrouter.com/blog/long-running-agents-timeouts-retries/)（2026-11-16 更新）。

# 长时间运行的智能体：可靠的超时、重试与检查点

BroadNet Inference 团队 · 阅读约 4 分钟 · 发布于 2026-11-14 · 更新于 2026-11-16

把每次模型调用视为可丢弃的，把智能体的状态视为持久的。为每次调用设置超时，用流式输出发现卡顿，对 429、5xx 和中断的流做有上限的退避重试，并给每个有副作用的工具一个幂等键。每一步后保存消息列表，这样崩溃后能从上一个检查点恢复，而不是从头开始。

## 要点

-   OpenAI Python SDK 默认 10 分钟超时、重试两次。用于智能体时，两者都要显式设置。
-   在 data \[DONE\] 之前就结束的流是不完整的回答。重试它就是一次新的推理，按量付费时会再次计费。
-   模型调用可以安全重试。工具副作用则不行，除非带有幂等键。
-   每完成一步就保存检查点：消息列表、步骤编号，以及已完成副作用的 ID。
-   在套餐会话中，重试不额外收费，但运行期间会占用那唯一的请求槽位。

**本页内容**

1.  智能体运行数小时会出什么问题？
2.  1\. 一次调用最多允许多长时间？
3.  2\. 长时间运行的智能体为什么要用流式输出？
4.  3\. 应该重试什么？
5.  4\. 怎样让工具调用幂等？
6.  5\. 怎样给智能体保存检查点？
7.  通宵运行前的检查清单
8.  BroadNet Inference 的定位

运行五分钟的智能体可以不管失败。运行五个小时的智能体则会遇到超时、429、中断的流，很可能还有一次重启。大多数讲长时间运行智能体的文章都在推销工作流引擎。你未必需要。本文介绍让一个普通的智能体循环连续运行数小时的五个习惯，并附上 OpenAI Python SDK 的代码。

## 智能体运行数小时会出什么问题？

| 故障 | 表现 | 应对的习惯 |
| --- | --- | --- |
| 调用卡死或太慢 | 几分钟都没有回复 | 每次调用的超时、流式输出 |
| 速率限制或过载 | 429、5xx | 有上限的退避重试 |
| 流中断 | 连接在 `[DONE]` 之前结束 | 视为不完整，重试这次调用 |
| 副作用重复 | 重试后工具运行了两次 | 幂等键 |
| 进程崩溃或部署 | 智能体从第 1 步重新开始 | 每一步保存检查点 |

## 1\. 一次调用最多允许多长时间？

OpenAI Python SDK 的 README 说，请求默认在 10 分钟后超时，某些错误会重试两次。用于智能体时，两者都自己设置，免得行为在你不知情时改变：

```python
client = OpenAI(base_url="https://inference.broadnet.ai/v1", api_key=os.environ["BROADNET_API_KEY"],
                timeout=300, max_retries=4)
```

超时要根据数据来定。把每次调用的耗时记录一天；把超时设得远高于最慢的成功调用。大的提示词启动更慢，[推理模型](https://broadrouter.com/zh/glossary/reasoning-tokens/)也会先思考再输出。按 约每秒 100 个 token 计算，单是 8,000 个输出 token 就要一分多钟。另外为每个**任务**设一个总时长预算，防止一个停不下来的循环跑上一整夜。

## 2\. 长时间运行的智能体为什么要用流式输出？

[流式输出](https://broadrouter.com/zh/glossary/streaming/)在模型工作时给你一个信号。没有它，慢调用和断掉的连接在超时触发之前看起来一模一样。有了它，你能看到数据块陆续到达，还能在最后一个数据块里拿到 token 用量。

BroadNet 的流式规则：一直读到字面上的 `data: [DONE]` 这一行。如果连接在此之前关闭，回答就是不完整的。记下 `X-Request-ID`，然后决定是否发起新请求。[完整的流式输出指南](https://broadrouter.com/zh/guides/streaming-chat-completions/)。

```python
def call_streaming(messages, tools=None):
    parts, done = [], False
    stream = client.chat.completions.create(
        model="broadnet/glm-5.3", messages=messages, tools=tools, stream=True,
        stream_options={"include_usage": True}, max_tokens=8000)
    for chunk in stream:
        if chunk.choices and chunk.choices[0].finish_reason:
            done = True
        if chunk.choices and chunk.choices[0].delta.content:
            parts.append(chunk.choices[0].delta.content)
    if not done:
        raise IncompleteStream()   # retry the whole call
    return "".join(parts)
```

这个示例只收集文本。如果你以流式方式接收工具调用，还要按 index 累积 `delta.tool_calls`。

## 3\. 应该重试什么？

SDK 已经会重试连接错误、408、409、429 和 5xx。只为它看不到的情况（比如不完整的流）在上面再加一层你自己的重试：

1.  **重试：** 连接错误、429、5xx、不完整的流。使用带随机抖动和上限的[指数退避](https://broadrouter.com/zh/glossary/exponential-backoff/)，例如最多 4 次。
2.  **修复，不要重试：** 400、401、402、403、413、422。这些错误每次都会以同样的方式失败。见[错误码以及何时重试](https://broadrouter.com/zh/guides/errors-and-retries/)。
3.  **按任务设置重试预算**，而不仅是按调用。十个步骤各重试四次，就是四十次额外调用。
4.  **重试用完后切换服务商。** 如果一次运行必须扛住服务商故障，就把连接错误、5xx 和限流导致的 429 转到第二个服务商。[大模型 API 故障切换](https://broadrouter.com/zh/blog/llm-api-failover-fallback/)给出了客户端代码和熔断器。

按量付费时，每次重试都是一次新的推理，会再次计费。按量付费的密钥还限制每分钟 30 个请求、同时 4 个进行中的请求，所以重试风暴很快就会撞上[速率限制](https://broadrouter.com/zh/glossary/rate-limit/)；[速率限制计算器](https://broadrouter.com/tools/llm-rate-limit-calculator/)能显示你的智能体还有多少余量。[429 处理一文](https://broadrouter.com/zh/blog/handle-llm-api-429-rate-limits/)详细讲了退避。在[不限量套餐](https://broadrouter.com/zh/guides/unlimited-llm-api-sessions/)上，重试不额外收费，但运行期间会占用会话唯一的请求槽位。

## 4\. 怎样让工具调用幂等？

模型调用没有副作用，工具调用可能有。如果智能体在 `send_invoice` 运行之后、步骤保存之前崩溃，重启后的智能体会再发一次。

给每个有副作用的调用一个由任务和步骤派生出的[幂等键](https://broadrouter.com/zh/glossary/idempotency-key/)，执行前先检查，如果已经记录过就跳过这次调用：

```python
def run_side_effect(task_id, step, call, store):
    key = f"{task_id}:{step}:{call.id}"
    if store.done(key):
        return store.result(key)       # already ran: return the saved result
    result = execute(call)             # pass key to the API if it supports one
    store.save(key, result)
    return result
```

许多支付和消息 API 接受幂等键请求头。如果支持，就把你的键传过去。

## 5\. 怎样给智能体保存检查点？

每完成一步就保存：消息列表、步骤编号和副作用的键。启动时，如果有最新的检查点就加载它。

```python
def save_checkpoint(path, step, messages):
    tmp = path + ".tmp"
    with open(tmp, "w") as f:
        json.dump({"step": step, "messages": messages}, f)
    os.replace(tmp, path)   # atomic on the same filesystem
```

先写入临时文件再重命名，意味着写到一半崩溃也绝不会留下半个检查点。对于非常长的会话，还要把**摘要**存进检查点：用简短的摘要替换旧的对话轮次，这样恢复后的智能体不必重新加载庞大的历史。这能让你保持在[上下文窗口](https://broadrouter.com/zh/glossary/context-window/)之内，即便是 [DeepSeek V4.1 Flash](https://broadrouter.com/zh/models/deepseek-v4.1-flash/) 的 1,048,576 token。

## 通宵运行前的检查清单

1.  在客户端上显式设置超时和 `max_retries`。
2.  开启流式输出并带上 `include_usage`，不完整的流要重试。
3.  每个任务有重试预算和总时长上限。
4.  每个会写入、发送或付款的工具都有幂等键。
5.  每一步后以原子方式写入检查点。
6.  日志包含步骤编号、耗时、token 数和 `X-Request-ID`。

如果你同时运行多个智能体，请阅读[用固定费用并行运行编程智能体](https://broadrouter.com/zh/blog/run-parallel-coding-agents-flat-rate/)和[多智能体方案的成本](https://broadrouter.com/zh/blog/multi-agent-cost/)。

## BroadNet Inference 的定位

BroadNet Inference 使用标准的 chat completions 流式输出，返回可记录的 `X-Request-ID` 响应头，并在文档中写明哪些错误应该重试，所以上面的模式可以照搬使用。对于整天运行的智能体，不限量套餐每个会话每月 $60，在 DeepSeek V4.1 Flash 上不计 token，重试因此免费。注意，Meteor 的一小时在购买一小时后结束，Orbit 的一周在七天后结束，所以长任务必须在这个期限内完成，或者改用会自动续期的 Full Moon 会话。套餐见 [inference.broadnet.ai/plans](https://inference.broadnet.ai/plans?utm_source=broadrouter&utm_medium=referral&utm_campaign=zh-blog-long-running-agents-timeouts-retries&utm_content=body)。

相关免费工具（英文）

-   [Agent run cost estimator](https://broadrouter.com/tools/agent-run-cost-estimator/) Context growth per step, total tokens and cost of one agent run, with a DeepSeek session comparison.
-   [LLM batch job planner](https://broadrouter.com/tools/llm-batch-job-planner/) Run time, binding limit, cost per model and the flat sessions needed to finish a big job by a deadline.
-   [Flat-rate vs per-token LLM cost calculator](https://broadrouter.com/tools/flat-rate-vs-per-token-calculator/) Break-even between an unlimited plan and paying per token, per agent.
-   [LLM rate limit and concurrency calculator](https://broadrouter.com/tools/llm-rate-limit-calculator/) Which limit binds first: RPM, TPM or concurrency, with Little's law.

[免费工具（英文）](https://broadrouter.com/tools/)

## 本文涉及的术语

[AI 智能体（AI agent）](https://broadrouter.com/zh/glossary/agent/)

AI 智能体是由语言模型自主决定步骤、朝目标推进的系统：它决定调用哪些工具、读取结果，然后重复，直到给出最终回答或触及上限。在固定位置调用模型的固定脚本，通常称为工作流（workflow）。

[Token（词元）](https://broadrouter.com/zh/glossary/token/)

token（词元）是大语言模型读写文本的基本单位：由模型的分词器切分出的一个词、词的一部分、一个标点或一段字节序列。大模型 API 按 token 计数、设定限制，通常也按 token 计费。

[幂等键（idempotency key）](https://broadrouter.com/zh/glossary/idempotency-key/)

幂等键是客户端附在会改变状态的请求（如付款或购买）上的唯一值，通常是 UUID 之类的随机 ID。如果用同一个键再次发送同一请求，服务器会返回原来的结果，而不会把操作执行两次。

[速率限制（rate limit）](https://broadrouter.com/zh/glossary/rate-limit/)

速率限制是 API 对客户端在一个时间窗口内的使用量设定的上限，例如每分钟请求数或每分钟 token 数。超出限制的请求会被拒绝，通常返回 HTTP 429 Too Many Requests，直到用量回落到限制以下。

[按量付费（pay-as-you-go）](https://broadrouter.com/zh/glossary/pay-as-you-go/)

按量付费是一种计价模式：你只为实际用量付费，按 token、请求次数或音频分钟等单位计量，没有订阅费，也没有最低消费承诺。大多数大模型 API 都这样计费，从预付余额中扣减或定期开具账单。

[大模型包月套餐（flat-rate LLM plan）](https://broadrouter.com/zh/glossary/flat-rate-llm-plan/)

大模型包月套餐（固定价格套餐）是按一个周期（如一个月）收取固定费用、提供大模型 API 使用权的计价方式，不按 token 计费。这类套餐通常会限制别的东西，如并发、速度、模型或使用时间窗口，所以限制条件和价格同样重要。

[流式输出（streaming）](https://broadrouter.com/zh/glossary/streaming/)

流式输出是一种在语言模型仍在生成时，就把回复分成小块陆续返回的方式，而不是在最后一次性返回。当请求把 stream 设为 true 时，OpenAI 兼容 API 会通过服务器发送事件（SSE）进行流式输出。

[指数退避（exponential backoff）](https://broadrouter.com/zh/glossary/exponential-backoff/)

指数退避（exponential backoff）是一种重试策略：客户端每失败一次，就等待更长时间再重试，通常把延迟翻倍，直到达到上限。在每次等待中加入随机抖动（jitter），可以把众多客户端的重试错开，避免它们在同一时刻打到服务器上。

## 常见问题

### 智能体里的大模型 API 调用，超时设多少合适？

要长到能容纳最慢的正常调用，又要短到能发现卡死的调用。OpenAI Python SDK 默认是 10 分钟。许多智能体在开启流式输出时每次调用设 2 到 5 分钟，并为每个任务另设一个总时长上限。

### 智能体应该重试哪些大模型 API 错误？

对连接错误、429 和 5xx 做有上限的指数退避重试，并加上随机抖动。400、401、402、403、413 和 422 要修复而不是重试。在 BroadNet 上，还要为每次失败记录 X-Request-ID 响应头。

### 重试一次 chat completion 安全吗？

模型调用本身没有副作用，所以安全，但它是一次新的推理，按量付费时会再次计费。危险在工具上。除非工具使用幂等键，否则重试的步骤可能会把同一封邮件发两次。

### 智能体崩溃后怎么恢复？

每完成一步就保存消息列表和步骤编号，在执行副作用之前写入其 ID，启动时重新加载。智能体会从上一个保存的步骤继续。

### 长时间运行的智能体需要不限量套餐吗？

不需要，但按量付费时重试和长上下文的费用会累积。在 BroadNet 的不限量套餐上，DeepSeek V4.1 Flash 不计 token，所以重试不额外收费，不过每个会话仍然一次只能运行一个请求。

## 继续阅读

-   [开源模型的工具调用：schema、并行调用与重试](https://broadrouter.com/zh/blog/tool-calling-open-models/)
-   [多智能体方案到底要花多少钱：按 token 计费 vs 固定价格会话](https://broadrouter.com/zh/blog/multi-agent-cost/)
-   [如何在固定价格大模型 API 上运行并行编程智能体](https://broadrouter.com/zh/blog/run-parallel-coding-agents-flat-rate/)
-   [大模型 API 套餐的“不限量”，到底意味着什么](https://broadrouter.com/zh/blog/what-unlimited-llm-api-really-means/)
-   [大模型 API 故障转移：在自己的代码里切换到备用服务商](https://broadrouter.com/zh/blog/llm-api-failover-fallback/)
-   [AI 编程智能体跑一次要花多少钱：步数、上下文增长与缓存](https://broadrouter.com/zh/blog/ai-coding-agent-run-cost/)
-   [Claude Code 接入开源模型：代理、原生端点与限制](https://broadrouter.com/zh/blog/claude-code-with-openai-compatible-models/)
-   [指南：BroadNet Inference 错误码，以及什么时候该重试](https://broadrouter.com/zh/guides/errors-and-retries/)
-   [指南：对话补全的流式输出，以及连接中断的处理](https://broadrouter.com/zh/guides/streaming-chat-completions/)
-   [指南：面向智能体的不限量 LLM API 套餐如何运作](https://broadrouter.com/zh/guides/unlimited-llm-api-sessions/)
-   [指南：用 OpenAI Python SDK 调用 BroadNet Inference](https://broadrouter.com/zh/guides/openai-python-sdk/)

用你的真实业务负载试一试。新账户可获得 US$5 初始额度，用于 Gemma和转写。DeepSeek、GLM和Qwen3.8 需要先充值。

[开始使用](https://inference.broadnet.ai/account/?utm_source=broadrouter&utm_medium=referral&utm_campaign=zh-blog-long-running-agents-timeouts-retries&utm_content=page-cta) ·

**来源**

-   [OpenAI Python SDK README：重试与超时（2026-11-14 查阅）](https://github.com/openai/openai-python)
-   [BroadNet Inference API 参考：错误与重试（英文）](https://inference.broadnet.ai/docs?utm_source=broadrouter&utm_medium=referral&utm_campaign=zh-blog-long-running-agents-timeouts-retries&utm_content=sources#errors)
-   [BroadNet Inference API 参考：流式输出与限制（英文）](https://inference.broadnet.ai/docs?utm_source=broadrouter&utm_medium=referral&utm_campaign=zh-blog-long-running-agents-timeouts-retries&utm_content=sources#requests)
-   [BroadNet Inference 不限量套餐（英文）](https://inference.broadnet.ai/plans?utm_source=broadrouter&utm_medium=referral&utm_campaign=zh-blog-long-running-agents-timeouts-retries&utm_content=sources)
