Temporal：持久化执行长时 Agent 工作流

为什么需要 Temporal：进程一崩一切重来，到崩溃后从断点续跑

构建跨多个 LLM 调用、外部 API、数据库写入的长时流程时，常见的做法是用一个常驻进程循环串起所有步骤。进程一旦被 OOM 杀死、发版重启、网络分区或 LLM 调用超时，整个流程状态全部丢失；为恢复状态只能手工重跑，或自建状态表、补偿逻辑和重试胶水代码。任务时长一旦超过几十分钟，这种脆弱性就会演变成生产事故。

Temporal 的解法是把工作流作为状态机运行在引擎中：每一次决策（调用了哪个 Activity、收到什么信号、定时器何时到期）都作为事件追加写入服务端数据库。Worker 不保存状态，崩溃重启后从事件历史重建执行现场，继续执行尚未完成的步骤；已完成的 Activity 直接从历史中读取上次结果，不会重复执行。重试、超时、心跳、信号等可靠性机制由引擎内建，业务代码不再需要手写。

与 LangChain/LangGraph 这类 Agent 框架不同，Temporal 不关心你如何构造 prompt 或编排工具调用，它的定位是承载这些 Agent 逻辑的执行底座。通过官方 temporalio-langchain 集成包，Agent 循环可以放进 Temporal 工作流运行，获得持久化与可恢复能力——两者是互补关系而非替代关系。

安装与环境配置：3 步就绪

步骤一·安装 CLI。Temporal CLI 内置一键启动的开发服务器（含 Server、Web UI、默认命名空间），是上手最快的路径。macOS 用 Homebrew 安装，Linux/CI 用官方安装脚本。

步骤二·启动开发环境。temporal server start-dev 在 localhost:7233 启动 gRPC 服务，并在 8233 端口提供 Web UI。需要完整自托管依赖（Server + Web UI + PostgreSQL + Elasticsearch）时，可直接拉取官方 docker-compose 仓库：git clone https://github.com/temporalio/docker-compose.git && cd docker-compose && docker compose up -d。

步骤三·验证安装。用 CLI 列出命名空间与工作流列表；浏览器打开 http://localhost:8233 看到 Web UI 即就绪。

# 1. 安装 Temporal CLIbrew install temporal                                          # macOScurl -sSf https://temporal.download/cli.sh | sh                # Linux / CI # 2. 启动本地开发环境（含 Web UI，默认 8233 端口）temporal server start-dev # 3. 验证安装temporal operator namespace listtemporal workflow list --namespace default

快速上手：30 分钟跑通第一个持久化 Agent 工作流

最小可用流程包含四步：安装 Python SDK、编写一个工作流（先执行 LLM 调用 Activity，再等待人工审批信号）、启动 Worker 消费任务队列、用 CLI 触发工作流。开发服务器自带持久化，无需额外配置数据库。

1. 安装 SDK：执行 pip install temporalio。

2. 创建 worker.py：定义 AgentWorkflow 与 call_llm Activity，代码见下方示例。

3. 启动 Worker：终端 1 运行 python worker.py，Worker 开始轮询 agent-demo 任务队列。

4. 触发工作流：终端 2 用 CLI 启动，指定任务队列、工作流 ID、工作流类型与 JSON 输入。

5. 观察等待状态：打开 UI（localhost:8233）查看事件历史，工作流在第一步完成后挂起，等待审批信号。

6. 发送信号放行：执行 temporal workflow signal 发送 approve 信号，工作流继续第二段调用并返回结果。

结果说明：在 UI 的事件历史中可看到每一步；杀掉 Worker 进程再重启，工作流会从最后一步继续而非从头开始。进阶技巧：接入真实 LLM 时，为 Activity 配置 heartbeat_timeout 并在长调用循环中上报心跳；需要复用 LangChain 组件时，使用官方 temporalio-langchain 集成包。

import asynciofrom datetime import timedeltafrom temporalio import activity, workflowfrom temporalio.client import Clientfrom temporalio.worker import Worker  # Activity：承载外部副作用（LLM API 调用）的环节@activity.defnasync def call_llm(prompt: str, step: int) -> str:    # 生产环境替换为真实 LLM API 调用，并定期发送心跳    return f"第{step}步已处理: {prompt}"  # Workflow：确定性编排逻辑，状态由服务端持久化@workflow.defnclass AgentWorkflow:    def __init__(self) -> None:        self.approved = False     @workflow.run    async def run(self, prompt: str) -> str:        await workflow.execute_activity(            call_llm, prompt, 1,            start_to_close_timeout=timedelta(minutes=5),            retry_policy=workflow.RetryPolicy(maximum_attempts=3),        )        # 等待人工审批信号，期间整个执行状态持久化在服务端        await workflow.wait_condition(lambda: self.approved)        return await workflow.execute_activity(            call_llm, prompt, 2,            start_to_close_timeout=timedelta(minutes=5),        )     @workflow.signal    async def approve(self) -> None:        self.approved = True  async def main() -> None:    client = await Client.connect("localhost:7233")    worker = Worker(client, task_queue="agent-demo", workflows=[AgentWorkflow])    await worker.run()  if __name__ == "__main__":    asyncio.run(main())

# 终端 1：启动 Workerpython worker.py # 终端 2：触发工作流temporal workflow start \  --task-queue agent-demo \  --workflow-id contract-review-001 \  --type AgentWorkflow \  --input '"分析这份合同的违约条款"' # 人工审批通过后，发送信号放行temporal workflow signal --workflow-id contract-review-001 --name approve # 查看完整事件历史temporal workflow show --workflow-id contract-review-001

核心能力详解：5 大支柱

支柱一·确定性执行与事件溯源。确定性执行（deterministic execution）指同一段工作流代码在相同输入下必然产生相同的执行轨迹——禁止在工作流内部读取系统时钟、生成随机数或直接调用外部 API。引擎以事件溯源（event sourcing）方式把每次决策追加写入事件历史；Worker 重启或缓存失效时，从空状态重放历史重建内存状态，保证恢复后行为与崩溃前完全一致。

支柱二·可靠的重试、超时与心跳。Activity 自动获得指数退避重试，可配置最大重试次数与退避系数，与 start_to_close_timeout（从开始到完成的超时）配合使用。对长达几十分钟到几小时的 LLM 调用或批处理任务，应开启心跳（heartbeat）：Worker 定期上报进度，服务端据此判断 Worker 是否失联，并在超时后把任务调度给其他 Worker，避免长任务白跑。

支柱三·人工审批与人机协作。Signal（信号）用于从外部向运行中的工作流注入数据，不阻塞发送方；Query（查询）只读获取当前状态，不产生副作用；Update 提供双向 RPC 语义。结合 workflow.wait_condition()，工作流可以无限期挂起等待人工在审批系统、IM 或 UI 中点击确认，期间状态完整持久化。

支柱四·子工作流与 Saga 补偿。子工作流（Child Workflow）用于把流程拆分为独立可管理的分段，支持并行扇出与聚合；父工作流跟踪所有子工作流状态。Saga 模式用于跨系统事务补偿：例如「先扣款再发货」的流程，发货 Activity 失败后执行退款补偿 Activity，保证数据最终一致。

支柱五·Nexus 跨命名空间编排。Nexus 是 Temporal 的跨命名空间调用协议，在 v1.24 正式 GA。大型组织可将不同团队的工作流按命名空间隔离，通过 Nexus 安全调用彼此的工作流，避免了把所有耦合塞进单一命名空间的运维噩梦，同时为每个命名空间设定独立的权限、限流与故障域。

生产部署与监控：从上线到运维

部署方式一·自托管 Kubernetes。生产环境推荐使用官方 Helm Chart（github.com/temporalio/helm-charts）部署在 Kubernetes 集群，存储后端可选 MySQL、PostgreSQL 或 Cassandra；实时检索、按任意属性过滤查询依赖高级可见性（Advanced Visibility），需要额外部署 Elasticsearch/OpenSearch。生产集群至少 3 个 Server 节点，升级前先核对 SDK 与 Server 的版本兼容矩阵。

部署方式二·Temporal Cloud（托管版）。由官方托管的命名空间服务，负责升级、扩缩容与高可用，按工作流执行量计费。适合不想运维基础组件的中型团队；自托管与 Cloud 在 SDK 层面完全一致，仅连接地址与鉴权方式不同，迁移成本低。

可观测性。Web UI 提供每个工作流的事件时间线（Event History）、轮次 JSON 视图与失败定位；CLI 的 temporal workflow show、temporal workflow list 用于命令行排查；各 SDK 内建 OpenTelemetry 支持，可导出链路追踪（Tracing）与指标（Metrics）到 Prometheus/Grafana。生产排障三板斧：先看事件历史中失败前的最后一条事件，再查 Activity 的重试次数与心跳间隔，最后结合 Worker 日志确认是否为代码确定性被破坏。

<p class="para-label">避坑清单：</p>

<ul class="dash-list"><li>工作流代码必须确定性：直接在工作流里调用外部 API、读取系统时间或随机数，会在恢复重放时执行多次导致状态错乱。所有副作用必须封装进 Activity。</li><li>Activity 会被自动重试，必须保证幂等：LLM 调用、扣款、发消息等操作重复执行是常态；长任务配置 heartbeat_timeout 并在循环中调用 heartbeat() 上报进度。</li><li>注意 SDK 与 Server 版本兼容：老版本 SDK 连接新版本 Server 会报 unsupported version；升级 Server 前先查官方兼容矩阵，避免线上事故。</li><li>大 Payload 限制：默认单条事件数据上限约 2MB（动态配置可调）。超大文档先写入对象存储，在工作流中只传引用，或用 Data Converter 做压缩与加密。</li></ul>

版本迭代

Temporal Server 保持约 6 周一个正式版本的节奏，主线围绕稳定性、可观测性与跨组织编排能力演进：2024 年重点落地 Nexus 跨命名空间协议，2025 年完成对状态引擎内部存储机制的 Transition History 重构。SDK 侧各语言持续追赶功能对齐。（截至训练数据，可能已有更新版本）

AI 应用场景

常见误区

面试题

参考来源

• webpageTemporal GitHub 主仓库Server 源码与 Release Notes