Temporal Python SDK Samples

You can expose a long-running Temporal Workflow's queries, updates, and signals as Nexus operations using two primary patterns depending on your requirements for lifecycle control and Workflow ID management.

Caller Pattern

Use this pattern when the Workflow is managed by a handler worker that starts it automatically on boot. The caller does not need to know the Workflow ID, as the handler manages it.

• Workflow Creation: The handler worker starts the Workflow on boot.
• Workflow ID: Managed internally by the handler.
• Nexus Service Example: NexusGreetingService

On-Demand Pattern

Use this pattern when the caller needs full control over the Workflow lifecycle and identity. The caller is responsible for creating the Workflow and providing the Workflow ID for every subsequent operation.

• Workflow Creation: The caller starts the Workflow via a Nexus operation.
• Workflow ID: The caller chooses and passes the ID in every operation.
• Nexus Service Example: NexusRemoteGreetingService

|                                | `callerpattern/`                     | `ondemandpattern/`                                                              |
|--------------------------------|--------------------------------------|--------------------------------------------------------------------------------|
| **Pattern**                    | Signal an existing Workflow          | Create and run Workflows on demand, and send signals to them                   |
| **Who creates the Workflow?** | The handler worker starts it on boot | The caller starts it via a Nexus operation                                    |
| **Who knows the Workflow ID?** | Only the handler                     | The caller chooses and passes it in every operation                            |
| **Nexus service**              | `NexusGreetingService`               | `NexusRemoteGreetingService`                                                  |

You can expose two different types of logic to a Gemini generate_content call using the SDK's automatic function-calling (AFC) loop. The choice depends on whether the logic is deterministic or involves I/O:

1. Activities as Tools: Use @activity.defn wrapped via activity_as_tool for any logic involving I/O, external APIs, or non-deterministic operations. These run as durable activities with configurable ActivityConfig (e.g., timeouts, retries).
2. Workflow Methods as Tools: Use plain workflow methods for pure, deterministic logic. These run directly within the workflow without an activity dispatch.

A single model prompt can trigger both patterns in a single execution loop.

# Pattern 1: Activity as a tool (for I/O or non-determinism)
@activity.defn
async def get_weather(location: str) -> str:
    ... 

# Pattern 2: Workflow method as a tool (for pure logic)
class ToolsWorkflow(workflow.Workflow):
    def recommend_thing_to_do(self, weather: str) -> str:
        ... 

Concept

The Resource Pool pattern uses a single long-lived ResourcePoolWorkflow to manage in-memory state for resource allocation. This allows for complex allocation logic that is decoupled from specific workers or task queues.

When to use this approach

Use this pattern when you need to:

• Manage a set of resources that is independent of your worker/task queue configuration.
• Execute arbitrary, complex logic to decide which workloads get which resources as they become available.

Limitations and Caveats

• Scaling: A single ResourcePoolWorkflow scales to tens of request/release events per second, but not hundreds. It is best suited for long-running workflows rather than high-frequency short tasks.
• Locking Risk: The sample uses true locking. If a workflow is terminated (rather than canceled) or times out, the resource may be leaked.
• Alternatives: For simpler concurrency management, consider using resource-specific task queues with limited activity slots, or using Sessions (available in the Go SDK) to pin workflows to workers.

The Message Filter Workflow demonstrates how to manage agent handoffs by selectively filtering message history. This is useful when switching agents to ensure the new agent receives a clean or relevant context.

In the provided example, the workflow follows this pattern:

1. Introduction: User greets the first agent.
2. Tool Usage: The first agent uses a function tool (e.g., generating a random number).
3. Agent Switch: The conversation transitions to a second agent for general queries.
4. Spanish Handoff: A second agent detects Spanish and hands off to a Spanish specialist.

Message Filtering Logic applied during handoff: When the handoff to the Spanish specialist occurs, the following filtering is applied to the message history:

• Tool Message Removal: All messages related to tool usage are stripped from the history.
• Selective Context Dropping: The first two messages of the conversation are dropped to demonstrate how to prune early context.

The workflow returns both the final response and the complete (filtered) message history for inspection.

The Caller Pattern is a design where a handler worker manages a specific Workflow (e.g., GreetingWorkflow) for a given User ID.

Key characteristics:

• Decoupled Workflow IDs: The caller does not need to know the specific Workflow ID. Instead, the caller provides a User ID, and the NexusGreetingServiceHandler resolves that User ID to the correct Workflow ID using a get_workflow_id mapping.
• Routing: The handler holds the User ID and routes all incoming Nexus operations to the corresponding workflow.
• Workflow Lifecycle: In this pattern, a caller workflow typically interacts with the target workflow through several Temporal primitives:
  1. Queries: To retrieve state (e.g., get_languages via @workflow.query).
  2. Updates: To change state (e.g., set_language via @workflow.update which triggers an activity).
  3. Signals: To trigger actions (e.g., approve via @workflow.signal).