# Temporal

Temporal is a durable execution platform that makes workflows survive crashes, retries and long waits. Learn workflows, activities, replay and its role in reliable agents.

## Overview

Temporal is an open-source platform for **durable execution**. It lets developers write a business process or an agent loop as ordinary code, and then guarantees that the code runs to completion even if servers crash, networks fail, external services time out or a step has to wait days for a person. When something breaks, Temporal does not start over. It resumes exactly where the process stopped, with all its variables intact.

Imagine writing a long letter by hand while someone keeps knocking the pen out of your hand. Without help, you might lose your place, repeat a paragraph or skip one. Temporal is like a scribe who records each sentence the moment you finish it. When you pick up the pen again, the scribe reads back what you have written and you continue from the next sentence, never repeating or skipping one.

This matters for AI agents because agents make many calls that can fail, such as model requests, tool calls and web requests, and they often need to wait for human approval. Durable execution turns a fragile chain of calls into a process that survives failure by design.

## What it is

Temporal has a server, called the Temporal Service, and SDKs that developers use to write code. Your code runs in your own processes, called workers. The service stores the state of every running workflow and hands work to workers.

| Concept | Meaning |
|---|---|
| Workflow | Deterministic code that defines the steps and their order |
| Activity | A function with side effects, such as calling an API, a database or a model |
| Worker | Your process that runs workflow and activity code |
| Task queue | A named queue through which the service sends work to workers |
| Event history | The durable, append-only record of everything a workflow has done |
| Replay | Rebuilding a workflow's state by re-running its code against its history |
| Retry policy | Rules for retrying failed activities, with backoff and limits |
| Timer | A durable wait, from seconds to months |
| Signal | A message sent into a running workflow, such as an approval |
| Query | A read-only request for a workflow's current state |
| Update | A request that changes a workflow and returns a result |
| Child workflow | A workflow started by another workflow |

The server is MIT-licensed and can be self-hosted. Temporal Technologies also offers Temporal Cloud, a managed service in which the company runs the Temporal Service and customers run their own workers.

## Where it came from

Temporal's founders, Maxim Fateev and Samar Abbas, had worked on the first public version of Amazon Simple Workflow Service. At Uber in 2015 they co-created Cadence, an open-source workflow engine used for many internal services. In 2019 they founded Temporal Technologies and began Temporal as a fork and successor of Cadence.

Since then Temporal has added official SDKs for Go, Java, TypeScript, Python, .NET, PHP and Ruby, with Rust in preview, and launched Temporal Cloud. As AI agents became common, Temporal positioned itself as a reliability layer for them: model and tool calls run as activities with automatic retries, and agent state survives failures. In July 2025 Temporal and OpenAI announced an integration that runs agents built with the [OpenAI Agents SDK](/tools/openai-agents-sdk) as durable Temporal workflows. Temporal also lists an integration with Google's [Agent Development Kit](/tools/google-adk).

## How it works

### Workflows and activities

You split your process into two kinds of code. **Workflow** code decides what happens next: call this activity, wait for that signal, branch on a result. It must be deterministic, which means given the same inputs and history it makes the same decisions. **Activity** code does the real work that touches the outside world, including model calls, which are not deterministic.

### Event history

When a workflow calls an activity, the service records that it was scheduled. When the activity finishes, the service records its result. Timers, signals and child workflows are recorded the same way. The history is the single source of truth.

### Replay

If a worker crashes, another worker picks up the workflow and replays its code from the start against the history. Each activity call that already has a recorded result returns that result immediately instead of running again. Within moments the code is back at the exact point where it stopped, with the same local variables, and it continues. This is why workflow code must be deterministic, and why changes to running workflow code need versioning.

### Retries and timeouts

Each activity has timeouts and a retry policy. If a model provider returns a temporary error, Temporal retries with backoff. Because retries can repeat an activity, activities should be idempotent where possible.

### Waiting for people and events

A workflow can wait on a timer or on a signal for as long as needed without holding a thread or a connection. For very long-lived workflows with large histories, "continue-as-new" starts a fresh run with carried-over state.

A short Python sketch of an approval step:

```python
from datetime import timedelta
from temporalio import activity, workflow

@activity.defn
async def extract_fields(doc_id: str) -> dict:
    ...  # call a model to read the document

@workflow.defn
class LoanApplication:
    def __init__(self) -> None:
        self.decision: str | None = None

    @workflow.signal
    def underwriter_decision(self, decision: str) -> None:
        self.decision = decision

    @workflow.run
    async def run(self, doc_id: str) -> str:
        await workflow.execute_activity(
            extract_fields, doc_id, start_to_close_timeout=timedelta(minutes=5)
        )
        await workflow.wait_condition(lambda: self.decision is not None)
        return self.decision
```

## Key concepts and terms

| Term | Meaning |
|---|---|
| Durable execution | Running code whose progress survives crashes and restarts |
| Determinism | The rule that workflow code makes the same decisions on replay |
| Idempotency | The property that repeating an activity causes no extra effect |
| Event history | The recorded log that defines a workflow's state |
| Replay | Re-running workflow code against history to restore state |
| Activity | A unit of side-effecting work with retries and timeouts |
| Signal | An asynchronous message into a running workflow |
| Query | A read of workflow state without changing it |
| Task queue | The channel connecting the service to a group of workers |
| Continue-as-new | Restarting a workflow with fresh history and carried state |
| Workflow versioning | Safely changing code while old runs are still active |

## A worked example

This is an illustrative scenario. A lender handles about 2,000 loan applications a week, each with uploaded documents and an AI step.

1. A web form starts a `LoanApplication` workflow with the application id.
2. Activity one asks a model to extract income, employer and address from the documents. The model provider times out on about 1 percent of calls; Temporal retries with backoff and almost all succeed on the second attempt.
3. Activity two calls a credit bureau. Activity three runs an agent that drafts a decision summary with reasons.
4. The workflow waits for an `underwriter_decision` signal. Some arrive in an hour, some after a weekend. No thread is held during the wait.
5. A query powers a status page that shows each application's current step.
6. During one deployment, all workers restart. Every in-flight application resumes from its last recorded step; no credit check runs twice.
7. If no decision arrives within ten working days, a timer fires and the workflow sends a reminder.

For audit, each application's history shows every step, input, output and retry.

## Strengths and limitations

**Strengths:**

- Strong reliability: processes survive crashes and resume precisely.
- Automatic retries, timeouts and durable timers.
- Long waits for people or events cost almost nothing.
- Full event history for debugging and audit.
- Business logic stays in ordinary code in many languages.

**Limitations:**

- A new programming model, especially the determinism rule.
- Changing code for running workflows needs careful versioning.
- You must run the service and its database, or pay for the managed cloud.
- Overkill for short, simple tasks that rarely fail.
- Large payloads in history can slow replay, so big data belongs in external storage.

## How it compares with alternatives

| Option | Choose it when | Trade-off |
|---|---|---|
| Temporal | Reliability, retries and long waits matter most | Learning curve and infrastructure |
| [Apache Airflow](/tools/apache-airflow) | You schedule batch data pipelines as DAGs | Not built for long-lived, event-driven processes |
| [Camunda](/tools/camunda) | Business-owned processes are modelled in BPMN | Model-first rather than code-first |
| [n8n](/tools/n8n) | Teams want quick visual app-to-app automation | Weaker durability guarantees for complex flows |
| Agent graph frameworks such as [LangGraph](/tools/langgraph) | You want agent-specific features with checkpointing | Lighter durability, narrower scope |

## Practical guidance and best practices

1. Put every side effect, including model, tool and HTTP calls, in activities.
2. Keep workflow code deterministic: no direct clocks, random numbers or network calls.
3. Set timeouts and retry policies per activity, matched to each dependency.
4. Make activities idempotent, for example with idempotency keys on external APIs.
5. Use signals or updates for human approvals and queries for status pages; see [human in the loop](/tools/human-in-the-loop).
6. Version workflow changes and test replay against recorded histories.
7. Keep large documents and model outputs in external storage and pass references.
8. Use compensating steps for multi-service changes; see the [saga pattern](/tools/saga-pattern).

## Common mistakes

- Calling a model or an API directly from workflow code.
- Using the system clock or random numbers in a workflow.
- Deploying changed workflow code without versioning, which breaks replay.
- Writing activities that are unsafe to retry, such as charging a card twice.
- Storing large files in workflow history.
- Using Temporal for a five-second task that a simple queue would handle.

## Frequently asked questions

### What is durable execution?

It is running code so that its progress is persisted step by step. After a crash, restart or long wait, the code continues from where it left off with its state intact, without repeating completed steps.

### Why use Temporal for AI agents?

Agents make many calls that can fail and often wait for people. Temporal retries failed calls, keeps agent state through crashes, waits cheaply for approvals and records every step, which turns a fragile agent loop into a dependable process.

### Why must workflow code be deterministic?

Because Temporal restores state by replaying workflow code against the recorded history. If the code made different decisions on replay, it would no longer match the history, so anything non-deterministic belongs in activities.

### Is Temporal open source?

Yes. The Temporal server and SDKs are open source under the MIT licence and can be self-hosted. Temporal Cloud is a paid managed service for the server side.

### How is Temporal different from a message queue?

A queue delivers messages, but you must build state, retries, timers and recovery yourself. Temporal provides those as part of the programming model and keeps the full history of each process.

### Which languages does Temporal support?

Official SDKs exist for Go, Java, TypeScript, Python, .NET, PHP and Ruby, with Rust in preview.

## Glossary

- Workflow: deterministic code defining a durable process.
- Activity: side-effecting work with retries.
- Worker: a process that runs workflow and activity code.
- History: the event log of a workflow.
- Replay: restoring state by re-running code against history.
- Signal: a message that changes a running workflow.
- Query: a read-only look at workflow state.
- Timer: a durable wait.
- Temporal Cloud: the managed version of the Temporal Service.
- Cadence: the Uber workflow engine from which Temporal grew.

## Summary

Temporal turns ordinary code into durable workflows by recording every step in an event history and replaying it to recover from failures. It grew out of Cadence at Uber and is MIT-licensed, with SDKs in many languages and a managed cloud. Activities carry side effects with retries and timeouts, timers and signals handle long waits and approvals, and queries expose status. For long-running processes and AI agents, it provides reliability that is hard to build by hand. Keep side effects in activities, workflows deterministic and versioned, and activities idempotent.