temporal

Temporal Workflows (Agentex)

Temporal is the durability layer for async Agentex agents. Every step is recorded as an immutable event; if the worker crashes, Temporal replays history to resume exactly where it left off.

When to Activate

• Building or editing a Temporal-based agent (manifest.yaml has temporal.enabled: true)
• Debugging workflow failures, retries, or signal handling
• Adding activities or custom I/O to an existing workflow
• Questions about failure recovery, event replay, or state persistence
• Implementing the state machine pattern inside a workflow

---

Project File Reading Order

Read in this order to build a complete mental model of any agent:

1. manifest.yaml — agent name, workflow name, queue name, env vars
2. project/models.py — state shape stored in MongoDB between turns
3. project/activities.py — real I/O (HTTP, DB, file); the only place non-deterministic work lives
4. project/acp.py — 5-line config wiring ACP → Temporal (no handlers needed here)
5. project/workflow.py — on_task_create (startup) + on_task_event_send (each user turn)
6. project/run_worker.py — wires activities + workflow + starts the worker process

---

Core Concepts

Event Sourcing / Replay

Temporal records every decision as an immutable event before executing it:

Event 1: WorkflowStarted
Event 2: ActivityScheduled  (scrape_url, url1)
Event 3: ActivityCompleted  (scrape_url, url1) → "scraped text"
Event 4: SignalReceived      (RECEIVE_EVENT)
Event 5: ActivityScheduled  (scrape_url, url2)
          ← worker crashes here

On restart, Temporal replays events 1–4. For completed activities it returns the recorded result (no real I/O). Execution resumes at Event 5 for real.

Determinism rule: Workflow code must produce the same decisions on every replay.

• ✅ Call activities for all I/O, random values, current time
• ❌ Never use random, time.time(), httpx, file reads directly in workflow code
• ❌ Never import I/O libraries at module level inside workflow files — use workflow.unsafe.imports_passed_through() if unavoidable