Merge branch 'main' into adk-activity-as-tool

Author: VegetarianOrc

nexus_messaging/callerpattern/README.md

@@ -1,12 +1,12 @@
 ## Caller pattern
 
 The handler worker starts a `GreetingWorkflow` for a User ID.
-`NexusGreetingServiceHandler` holds that ID and routes every Nexus operation to it.
+`NexusGreetingServiceHandler` derives the Workflow ID and routes every Nexus operation to it.
 The caller's input does not have that Workflow ID as the caller doesn't know it -- but the caller
 sends in the User ID, and `NexusGreetingServiceHandler` knows how to get the desired Workflow ID
 from that User ID (see the `get_workflow_id` call).
 
-The handler worker uses the same `get_workflow_id` call to generate a Workflow ID from a Wser ID
+The handler worker uses the same `get_workflow_id` call to generate a Workflow ID from a User ID
 when it launches the Workflow.
 
 The caller Workflow:

nexus_messaging/callerpattern/handler/service_handler.py

@@ -8,7 +8,7 @@
 
 import nexusrpc
 from temporalio import nexus
-from temporalio.client import WorkflowHandle
+from temporalio.client import Client, WorkflowHandle
 
 from nexus_messaging.callerpattern.handler.workflows import GreetingWorkflow
 from nexus_messaging.callerpattern.service import (
@@ -38,43 +38,61 @@ def get_workflow_id(user_id: str) -> str:
 @nexusrpc.handler.service_handler(service=NexusGreetingService)
 class NexusGreetingServiceHandler:
     def _get_workflow_handle(
-        self, user_id: str
+        self, client: Client, user_id: str
     ) -> WorkflowHandle[GreetingWorkflow, str]:
-        return nexus.client().get_workflow_handle_for(
+        return client.get_workflow_handle_for(
             GreetingWorkflow.run, get_workflow_id(user_id)
         )
 
-    @nexusrpc.handler.sync_operation
+    @nexus.temporal_operation
     async def get_languages(
-        self, ctx: nexusrpc.handler.StartOperationContext, input: GetLanguagesInput
-    ) -> GetLanguagesOutput:
-        return await self._get_workflow_handle(input.user_id).query(
+        self,
+        _ctx: nexus.TemporalStartOperationContext,
+        client: nexus.TemporalNexusClient,
+        input: GetLanguagesInput,
+    ) -> nexus.TemporalOperationResult[GetLanguagesOutput]:
+        result = await self._get_workflow_handle(client.client, input.user_id).query(
             GreetingWorkflow.get_languages, input
         )
+        return nexus.TemporalOperationResult.sync(result)
 
-    @nexusrpc.handler.sync_operation
+    @nexus.temporal_operation
     async def get_language(
-        self, ctx: nexusrpc.handler.StartOperationContext, input: GetLanguageInput
-    ) -> Language:
-        return await self._get_workflow_handle(input.user_id).query(
+        self,
+        _ctx: nexus.TemporalStartOperationContext,
+        client: nexus.TemporalNexusClient,
+        input: GetLanguageInput,
+    ) -> nexus.TemporalOperationResult[Language]:
+        result = await self._get_workflow_handle(client.client, input.user_id).query(
             GreetingWorkflow.get_language
         )
+        return nexus.TemporalOperationResult.sync(result)
 
     # Routes to set_language_using_activity (not set_language) so that new languages not
     # already in the greetings map can be fetched via an activity.
-    @nexusrpc.handler.sync_operation
+    @nexus.temporal_operation
     async def set_language(
-        self, ctx: nexusrpc.handler.StartOperationContext, input: SetLanguageInput
-    ) -> Language:
-        return await self._get_workflow_handle(input.user_id).execute_update(
-            GreetingWorkflow.set_language_using_activity, input
+        self,
+        _ctx: nexus.TemporalStartOperationContext,
+        client: nexus.TemporalNexusClient,
+        input: SetLanguageInput,
+    ) -> nexus.TemporalOperationResult[Language]:
+        result = await self._get_workflow_handle(
+            client.client, input.user_id
+        ).execute_update(
+            GreetingWorkflow.set_language_using_activity,
+            input,
         )
+        return nexus.TemporalOperationResult.sync(result)
 
-    @nexusrpc.handler.sync_operation
+    @nexus.temporal_operation
     async def approve(
-        self, ctx: nexusrpc.handler.StartOperationContext, input: ApproveInput
-    ) -> ApproveOutput:
-        await self._get_workflow_handle(input.user_id).signal(
+        self,
+        _ctx: nexus.TemporalStartOperationContext,
+        client: nexus.TemporalNexusClient,
+        input: ApproveInput,
+    ) -> nexus.TemporalOperationResult[ApproveOutput]:
+        await self._get_workflow_handle(client.client, input.user_id).signal(
             GreetingWorkflow.approve, input
         )
-        return ApproveOutput()
+        return nexus.TemporalOperationResult.sync(ApproveOutput())

nexus_messaging/ondemandpattern/handler/service_handler.py

@@ -1,13 +1,15 @@
 """
 Nexus operation handler for the on-demand pattern. Each operation receives the target
-userId in its input, and run_from_remote starts a brand-new GreetingWorkflow.
+user_id in its input, and run_from_remote starts a brand-new GreetingWorkflow. Operations
+use Temporal operation handlers so the SDK can manage their lifecycle and link the caller's
+Nexus operation to the target Workflow.
 """
 
 from __future__ import annotations
 
 import nexusrpc
 from temporalio import nexus
-from temporalio.client import WorkflowHandle
+from temporalio.client import Client, WorkflowHandle
 
 from nexus_messaging.ondemandpattern.handler.workflows import GreetingWorkflow
 from nexus_messaging.ondemandpattern.service import (
@@ -31,9 +33,9 @@ def _get_workflow_id(self, user_id: str) -> str:
         return WORKFLOW_ID_PREFIX + user_id
 
     def _get_workflow_handle(
-        self, user_id: str
+        self, client: Client, user_id: str
     ) -> WorkflowHandle[GreetingWorkflow, str]:
-        return nexus.client().get_workflow_handle_for(
+        return client.get_workflow_handle_for(
             GreetingWorkflow.run, self._get_workflow_id(user_id)
         )
 
@@ -48,37 +50,55 @@ async def run_from_remote(
             id=self._get_workflow_id(input.user_id),
         )
 
-    @nexusrpc.handler.sync_operation
+    @nexus.temporal_operation
     async def get_languages(
-        self, ctx: nexusrpc.handler.StartOperationContext, input: GetLanguagesInput
-    ) -> GetLanguagesOutput:
-        return await self._get_workflow_handle(input.user_id).query(
+        self,
+        _ctx: nexus.TemporalStartOperationContext,
+        client: nexus.TemporalNexusClient,
+        input: GetLanguagesInput,
+    ) -> nexus.TemporalOperationResult[GetLanguagesOutput]:
+        result = await self._get_workflow_handle(client.client, input.user_id).query(
             GreetingWorkflow.get_languages, input
         )
+        return nexus.TemporalOperationResult.sync(result)
 
-    @nexusrpc.handler.sync_operation
+    @nexus.temporal_operation
     async def get_language(
-        self, ctx: nexusrpc.handler.StartOperationContext, input: GetLanguageInput
-    ) -> Language:
-        return await self._get_workflow_handle(input.user_id).query(
+        self,
+        _ctx: nexus.TemporalStartOperationContext,
+        client: nexus.TemporalNexusClient,
+        input: GetLanguageInput,
+    ) -> nexus.TemporalOperationResult[Language]:
+        result = await self._get_workflow_handle(client.client, input.user_id).query(
             GreetingWorkflow.get_language,
         )
+        return nexus.TemporalOperationResult.sync(result)
 
     # Routes to set_language_using_activity so that new languages not already in the
     # greetings map can be fetched via an activity.
-    @nexusrpc.handler.sync_operation
+    @nexus.temporal_operation
     async def set_language(
-        self, ctx: nexusrpc.handler.StartOperationContext, input: SetLanguageInput
-    ) -> Language:
-        return await self._get_workflow_handle(input.user_id).execute_update(
-            GreetingWorkflow.set_language_using_activity, input
+        self,
+        _ctx: nexus.TemporalStartOperationContext,
+        client: nexus.TemporalNexusClient,
+        input: SetLanguageInput,
+    ) -> nexus.TemporalOperationResult[Language]:
+        result = await self._get_workflow_handle(
+            client.client, input.user_id
+        ).execute_update(
+            GreetingWorkflow.set_language_using_activity,
+            input,
         )
+        return nexus.TemporalOperationResult.sync(result)
 
-    @nexusrpc.handler.sync_operation
+    @nexus.temporal_operation
     async def approve(
-        self, ctx: nexusrpc.handler.StartOperationContext, input: ApproveInput
-    ) -> ApproveOutput:
-        await self._get_workflow_handle(input.user_id).signal(
+        self,
+        _ctx: nexus.TemporalStartOperationContext,
+        client: nexus.TemporalNexusClient,
+        input: ApproveInput,
+    ) -> nexus.TemporalOperationResult[ApproveOutput]:
+        await self._get_workflow_handle(client.client, input.user_id).signal(
             GreetingWorkflow.approve, input
         )
-        return ApproveOutput()
+        return nexus.TemporalOperationResult.sync(ApproveOutput())

openai_agents/README.md

@@ -39,4 +39,5 @@ Each directory contains a complete example with its own README for detailed inst
 - **[Customer Service](./customer_service/README.md)** - Interactive customer service agent with escalation capabilities, demonstrating conversational workflows.
 - **[Reasoning Content](./reasoning_content/README.md)** - Example of how to retrieve the thought process of reasoning models.
 - **[Financial Research Agent](./financial_research_agent/README.md)** - Multi-agent financial research system with planner, search, analyst, writer, and verifier agents collaborating.
+- **[Sandbox](./sandbox/README.md)** - `SandboxAgent` with a shell and filesystem, where every sandbox operation runs as a Temporal activity. **Pre-release.**
 - **[Streaming](./streaming/README.md)** - `Runner.run_streamed` with buffered token streaming to external subscribers via `temporalio.contrib.workflow_streams`. **Experimental.**

openai_agents/agent_patterns/workflows/agents_as_tools_workflow.py

@@ -8,6 +8,7 @@
 """
 
 
+# @@@SNIPSTART python-openai-agents-agent-as-tool-workflow
 def orchestrator_agent() -> Agent:
     spanish_agent = Agent(
         name="spanish_agent",
@@ -52,6 +53,9 @@ def orchestrator_agent() -> Agent:
     return orchestrator_agent
 
 
+# @@@SNIPEND
+
+
 def synthesizer_agent() -> Agent:
     return Agent(
         name="synthesizer_agent",

openai_agents/basic/activities/get_weather_activity.py

@@ -1,3 +1,4 @@
+# @@@SNIPSTART python-openai-agents-weather-activity
 from dataclasses import dataclass
 
 from temporalio import activity
@@ -16,3 +17,6 @@ async def get_weather(city: str) -> Weather:
     Get the weather for a given city.
     """
     return Weather(city=city, temperature_range="14-20C", conditions="Sunny with wind.")
+
+
+# @@@SNIPEND

openai_agents/basic/run_hello_world_workflow.py

@@ -8,6 +8,7 @@
 
 async def main():
     # Create client connected to server at the given address
+    # @@@SNIPSTART python-openai-agents-hello-world-client
     client = await Client.connect(
         "localhost:7233",
         plugins=[
@@ -23,6 +24,7 @@ async def main():
         task_queue="openai-agents-basic-task-queue",
     )
     print(f"Result: {result}")
+    # @@@SNIPEND
 
 
 if __name__ == "__main__":

openai_agents/basic/run_worker.py

@@ -34,6 +34,7 @@
 
 async def main():
     # Create client connected to server at the given address
+    # @@@SNIPSTART python-openai-agents-hello-world-worker
     client = await Client.connect(
         "localhost:7233",
         plugins=[
@@ -44,6 +45,7 @@ async def main():
             ),
         ],
     )
+    # @@@SNIPEND
 
     worker = Worker(
         client,

openai_agents/basic/workflows/hello_world_workflow.py

@@ -1,3 +1,4 @@
+# @@@SNIPSTART python-openai-agents-hello-world-workflow
 from agents import Agent, Runner
 from temporalio import workflow
 
@@ -13,3 +14,6 @@ async def run(self, prompt: str) -> str:
 
         result = await Runner.run(agent, input=prompt)
         return result.final_output
+
+
+# @@@SNIPEND

openai_agents/basic/workflows/tools_workflow.py

@@ -9,6 +9,7 @@
 from openai_agents.basic.activities.get_weather_activity import get_weather
 
 
+# @@@SNIPSTART python-openai-agents-activity-tool-workflow
 @workflow.defn
 class ToolsWorkflow:
     @workflow.run
@@ -25,3 +26,6 @@ async def run(self, question: str) -> str:
 
         result = await Runner.run(agent, input=question)
         return result.final_output
+
+
+# @@@SNIPEND