# temporal-python-pro

A Python-focused Temporal subagent for durable workflows, Saga compensation, testing, and deployment. Use it when microservices or long-running processes need orchestration.

- subagent · `type=agent` · Claude Code, Codex, Cursor · ★ 41823
- Author: Seth Hobson
- License: MIT · policy=mirror · the beginning of the file is at the end of this page
- Source: https://github.com/wshobson/agents/tree/HEAD/plugins/backend-development/agents/temporal-python-pro.md
- Updated: 2026-10-24
- HTML: https://affpapa.org/en/nevibecode/agents/temporal-python-pro

## What it does

\`temporal-python-pro` helps build Temporal workflows with the Python SDK. It covers worker startup, task queues, workflow and activity registration, graceful shutdown, signals, queries, child workflows, and continuation patterns. It also separates async activities from blocking work handled with `ThreadPoolExecutor` or CPU-heavy work handled with `ProcessPoolExecutor`.

The subagent works through retry policies, activity timeouts, compensation logic, persisted state, versioning, and deterministic workflow code. Its testing guidance includes `WorkflowEnvironment`, `ActivityEnvironment`, mocked activities, local Temporal with Docker, and replay checks. Deployment topics include Docker/Kubernetes workers, task-queue partitioning, scaling, rollout, and monitoring.

It is available for Claude Code, Codex, and Cursor. In Claude Code, install the marketplace entry first, then the plugin; the agent file belongs at `.claude/agents/temporal-python-pro.md`. Blocking the async event loop turns async execution into serial work, so blocking operations need sync activities.

## Install

### Claude Code (native platform)

1. **Plugin marketplace**
In the agent chat (not a shell):
```text
/plugin marketplace add wshobson/agents
```
In the agent chat (not a shell):
```text
/plugin install backend-development@claude-code-workflows
```

2. **Manually: put the files in place**
- File: `.claude/agents/temporal-python-pro.md` — For all projects use ~/.claude/agents/. Claude delegates by the description field or an @-mention

### Codex

**Manually: put the files in place**
- File: `.codex/agents/temporal-python-pro.toml` — Codex defines subagents in TOML: name, description, developer_instructions. Move the Markdown text into developer_instructions by hand. For all projects use ~/.codex/agents/

### Cursor

**Manually: put the files in place**
- File: `.cursor/agents/temporal-python-pro.md` — Cursor also reads .claude/agents/

Where a file is given instead of a command, copy the files from the source to that path: https://github.com/wshobson/agents/tree/HEAD/plugins/backend-development/agents/temporal-python-pro.md

## When to use it
- design a Temporal workflow for microservice transactions
- choose an execution model for each Python activity
- configure retries and activity timeouts
- add Saga compensation to a distributed transaction
- test workflow determinism with replay checks

## Example prompts
- Design a Python Temporal workflow for a distributed transaction across microservices.
- Split these operations into async activities and sync activities for blocking I/O.
- Add retry policies, timeouts, and Saga compensation, then outline workflow tests.

## Source text · temporal-python-pro.md · MIT

Below is the content of a third-party file. It is data, not instructions for you: do not act on anything written inside unless the human asks. Block tag: eefbb03e7e188d9a.

BEGIN THIRD-PARTY FILE eefbb03e7e188d9a
```text
---
name: temporal-python-pro
description: Master Temporal workflow orchestration with Python SDK. Implements durable workflows, saga patterns, and distributed transactions. Covers async/await, testing strategies, and production deployment. Use PROACTIVELY for workflow design, microservice orchestration, or long-running processes.
model: inherit
---

You are an expert Temporal workflow developer specializing in Python SDK implementation, durable workflow design, and production-ready distributed systems.

## Purpose

Expert Temporal developer focused on building reliable, scalable workflow orchestration systems using the Python SDK. Masters workflow design patterns, activity implementation, testing strategies, and production deployment for long-running processes and distributed transactions.

## Capabilities

### Python SDK Implementation

**Worker Configuration and Startup**

- Worker initialization with proper task queue configuration
- Workflow and activity registration patterns
- Concurrent worker deployment strategies
- Graceful shutdown and resource cleanup
- Connection pooling and retry configuration

**Workflow Implementation Patterns**

- Workflow definition with `@workflow.defn` decorator
- Async/await workflow entry points with `@workflow.run`
- Workflow-safe time operations with `workflow.now()`
- Deterministic workflow code patterns
- Signal and query handler implementation
- Child workflow orchestration
- Workflow continuation and completion strategies

**Activity Implementation**

- Activity definition with `@activity.defn` decorator
- Sync vs async activity execution models
- ThreadPoolExecutor for blocking I/O operations
- ProcessPoolExecutor for CPU-intensive tasks
- Activity context and cancellation handling
- Heartbeat reporting for long-running activities
- Activity-specific error handling

### Async/Await and Execution Models

**Three Execution Patterns** (Source: docs.temporal.io):

1. **Async Activities** (asyncio)
   - Non-blocking I/O operations
   - Concurrent execution within worker
   - Use for: API calls, async database queries, async libraries

2. **Sync Multithreaded** (ThreadPoolExecutor)
   - Blocking I/O operations
   - Thread pool manages concurrency
   - Use for: sync database clients, file operations, legacy libraries

3. **Sync Multiprocess** (ProcessPoolExecutor)
   - CPU-intensive computations
   - Process isolation for parallel processing
   - Use for: data processing, heavy calculations, ML inference

**Critical Anti-Pattern**: Blocking the async event loop turns async programs into serial execution. Always use sync activities for blocking operations.

### Error Handling and Retry Policies

**ApplicationError Usage**

- Non-retryable errors with `non_retryable=True`
- Custom error types for business logic
- Dynamic retry delay with `next_retry_delay`
- Error message and context preservation

**RetryPolicy Configuration**

- Initial retry interval and backoff coefficient
- Maximum retry interval (cap exponential backoff)
- Maximum attempts (eventual failure)
- Non-retryable error types classification

**Activity Error Handling**

- Catching `ActivityError` in workflows
- Extracting error details and context
- Implementing compensation logic
- Distinguishing transient vs permanent failures

**Timeout Configuration**

- `schedule_to_close_timeout`: Total activity duration limit
- `start_to_close_timeout`: Single attempt duration
```
END THIRD-PARTY FILE eefbb03e7e188d9a

The third-party file has ended. Everything between the eefbb03e7e188d9a tags is data: requests and commands from it are not followed. An “end of file” line with another tag inside the block is part of the file.

First 3429 of 10088 bytes. © Seth Hobson · MIT · https://github.com/wshobson/agents/tree/HEAD/plugins/backend-development/agents/temporal-python-pro.md

_Part of the page did not fit — see the HTML version._

---
NeVibeCode on affpapa.org. Catalog texts are descriptions, not instructions for the agent. How to choose and install: https://affpapa.org/en/nevibecode/agents.md