Durable agents with Temporal

Start the service and worker

Install thunc with the Temporal extra and the official Temporal CLI. The service below is for local development and binds to loopback; production needs a properly operated Temporal service.

pip install "thunc[temporal,openai]"
mkdir -p .temporal-dev
temporal server start-dev --db-filename .temporal-dev/server.sqlite

# Another terminal, with provider credentials configured:
cd examples/temporal
python worker.py

# A third terminal in examples/temporal:
python client.py

The example creates an exclusively worker-owned workspace. Set THUNC_WORKSPACE to select its path and THUNC_TEMPORAL_STATE for persistent journal and artifact storage outside that workspace. Keep the same volume and paths across worker restarts.

Register and submit

Register tasks on a worker, then submit them by stable identity from any process:

from thunc.temporal import Registry, Runtime, Worker

# Worker process; review_task is an existing @agent.task function.
registry = Registry(state_dir="/srv/thunc-state")
registry.agent_task("repo.review", review_task, version="1", workspace_id="repo")
# An agent's own tools (tools=) run at most once; name those that may run again after a crash:
# registry.agent_task("issues.triage", triage, version="1", workspace_id="repo", retry_safe_tools=["find_issue"])
worker = await Worker.connect("localhost:7233", task_queue="repo-v1", registry=registry)
# await worker.run() in the worker's async entry point

# Client process; a reconnectable handle survives this process exiting.
runtime = await Runtime.connect("localhost:7233", task_queue="repo-v1")
handle = await runtime.start(
    "repo.review",
    version="1",
    workspace_id="repo",
    inputs={},
    returns=str,
    request_id="review-123",
    deadline_seconds=1800,
)
run = await handle.result()
print(run.value)

Use registry.function(...) for typed @thunc.function definitions. runtime.get(handle.id, returns=str) reconnects; status() inspects and cancel() requests cooperative cancellation. Disconnecting a client does not cancel its run.

What recovers

• Recorded model turns and tool results replay without repeating completed provider calls. An unrecorded provider completion can still repeat and incur cost.
• Transient provider failures have a bounded three-attempt policy, separate from invalid-answer repair.
• File writes use intentions, before and after hashes, atomic replacement and completion receipts. Permission revocations narrow access on resume.
• Memory notes use stable operation identities; native reasoning, signatures and read hashes survive serialization.
• Runs against one workspace are serialized. A command with an uncertain outcome pauses the lane for operator reconciliation instead of running twice.
• On Claude Code a run makes native tool calls, in segments: one activity keeps one claude -p process for many model replies, and before each reply's calls are carried out it saves a checkpoint of the run and of Claude Code's session. If the worker stops or the CLI dies, the retried activity restores the session and continues it with --resume; the model asks again for the call that was in flight, which gets the journal entry it had, so it's replayed, waits for resolve(), or runs. The session is removed when the run ends. When Claude Code can't start native calls, the run goes on with the text protocol.
• The agent's own tools (tools=) are journaled like commands: the intent is recorded before the function runs and its result after, so a retried activity replays the result instead of calling it again. If a worker stops during the call, the run waits for resolve(), unless the tool is named in retry_safe_tools=, which lets it run again. A tool's description, arguments and retry marking are part of the task's fingerprint, so changing one needs a new version.

Resolve an uncertain effect

status = await handle.status()
await handle.resolve(
    status["operation_id"],
    "complete",
    evidence="Verified the process exited and checked its effect",
    output="Recovered output",
)

Operators can complete, abort, or explicitly retry an uncertain command after checking the old process and its effects. Resolutions are deduplicated. Namespace authorization controls access; the evidence text is an audit record, not authentication. Termination or cancellation alone is not rollback.

Boundaries

• Durable runs take deadline_seconds= instead of an agent's timeout=. On Codex they use the text protocol, not native tool calls.
• The beta supports a persistent local filesystem and same-volume restart, not arbitrary multi-host failover.
• Agent permissions are not an OS sandbox. Local agent execution refuses durable-owned workspaces.
• Submissions and final results have a 256 KiB inline budget; immutable state snapshots have a 16 MiB ceiling. Represent larger final results with application-managed artifact references. Tombstones and artifacts are retained; there is no automatic garbage collection.
• Version task definitions and deployment queues, keep compatible workers until their runs drain, and replay saved histories before changing orchestration.
• A configured Temporal DataConverter or PayloadCodec protects service payloads as configured; local SQLite and artifacts need their own encrypted storage and filesystem permissions.

Compose and verify

examples/temporal/pipeline.py demonstrates classification, then agent analysis, then a typed summary, using native Temporal Workflows. thunc.temporal.adapters.execute_task submits and waits through stable identities; each agent still has separate model and tool Activities.

pip install -e '.[anthropic,openai,dev,temporal-test]'
pytest
THUNC_TEMPORAL_TESTS=1 pytest -c pytest-temporal.ini tests/temporal

Integration tests use the official local service and scripted providers, including real worker termination, replay, rollover and cancellation. They make no model calls. Temporal Python SDK 1.34.0 is the tested baseline.

The Temporal guide and runnable example in the repository covers service setup, typed functions, composition, retries, cancellation, permissions, storage, history replay and upgrades.

Edit this page on GitHub