Adding cahnges to openai agents temporal sdk tutorials

jasonyang101 · jasonyang101 · commit 3aff9ff6d3f3 · 2025-10-16T21:26:25.000-07:00
diff --git a/examples/tutorials/10_agentic/10_temporal/060_open_ai_agents_sdk_hello_world/README.md b/examples/tutorials/10_agentic/10_temporal/060_open_ai_agents_sdk_hello_world/README.md
@@ -1,11 +1,53 @@
 # [Temporal] OpenAI Agents SDK - Hello World
 
+**Part of the [OpenAI SDK + Temporal integration series](../README.md)**
+
 ## What You'll Learn
 
 The OpenAI Agents SDK plugin automatically converts LLM calls into durable Temporal activities. When `Runner.run()` executes, the LLM invocation becomes an `invoke_model_activity` visible in Temporal UI with full observability, automatic retries, and durability.
 
 **Key insight:** You don't need to wrap agent calls in activities manually - the plugin handles this automatically, making non-deterministic LLM calls work seamlessly in Temporal workflows.
 
+## Prerequisites
+
+1. Agentex backend running with Temporal (`make dev` in agentex repo)
+2. OpenAI API key configured (see setup below)
+
+## Setup
+
+This tutorial uses the OpenAI Agents SDK plugin, which needs to be added in two places:
+
+### 1. Add Plugin to ACP (`project/acp.py`)
+```python
+from agentex.lib.plugins.openai_agents import OpenAIAgentsPlugin
+
+acp = FastACP.create(
+    config=TemporalACPConfig(
+        plugins=[OpenAIAgentsPlugin()]  # Add this
+    )
+)
+```
+
+### 2. Add Plugin to Worker (`project/run_worker.py`)
+```python
+from agentex.lib.plugins.openai_agents import OpenAIAgentsPlugin
+
+worker = AgentexWorker(
+    task_queue=task_queue_name,
+    plugins=[OpenAIAgentsPlugin()],  # Add this
+)
+```
+
+### 3. Configure OpenAI API Key
+Add to `manifest.yaml`:
+```yaml
+secrets:
+  - name: OPENAI_API_KEY
+    value: "your-openai-api-key-here"
+```
+
+Or set in `.env` file: `OPENAI_API_KEY=your-key-here`
+
 ## Quick Start
 
 ```bash
@@ -18,10 +60,17 @@ uv run agentex agents run --manifest manifest.yaml
 ## Try It
 
 1. Send a message to the agent (it responds in haikus)
-2. Open Temporal UI at http://localhost:8080
-3. Find your workflow execution
-4. Look for the `invoke_model_activity` - this was created automatically
-5. Inspect the activity to see:
+2. Check the agent response:
+
+![Agent Response](../_images/hello_world_response.png)
+
+3. Open Temporal UI at http://localhost:8080
+4. Find your workflow execution
+5. Look for the `invoke_model_activity` - this was created automatically:
+
+![Temporal UI](../_images/hello_world_temporal.png)
+
+6. Inspect the activity to see:
    - Input parameters (your message)
    - Output (agent's haiku response)
    - Execution time
diff --git a/examples/tutorials/10_agentic/10_temporal/070_open_ai_agents_sdk_tools/README.md b/examples/tutorials/10_agentic/10_temporal/070_open_ai_agents_sdk_tools/README.md
@@ -1,5 +1,7 @@
 # [Temporal] OpenAI Agents SDK - Tools
 
+**Part of the [OpenAI SDK + Temporal integration series](../README.md)** → Previous: [060 Hello World](../060_open_ai_agents_sdk_hello_world/)
+
 ## What You'll Learn
 
 Two patterns for making agent tools durable with Temporal:
@@ -15,6 +17,10 @@ Two patterns for making agent tools durable with Temporal:
 - 1:many mapping - your code controls execution order, not the LLM
 - Ensures atomic operations (withdraw always happens before deposit)
 
+## Prerequisites
+
+See [Hello World tutorial](../060_open_ai_agents_sdk_hello_world/) for basic setup of the OpenAI Agents SDK plugin.
+
 ## Quick Start
 
 ```bash
@@ -26,35 +32,131 @@ uv run agentex agents run --manifest manifest.yaml
 
 ## Try It
 
-**Pattern 1 (implemented):** Ask "What's the weather in San Francisco?"
-- Open Temporal UI (localhost:8080)
-- See a single `get_weather` activity created
-- The activity shows the external call with retry capability
+### Pattern 1: Single Activity Tool
+
+Ask "What's the weather in San Francisco?"
+
+1. Check the agent response:
+
+![Weather Response](../_images/weather_response.png)
+
+2. Open Temporal UI (localhost:8080)
+3. See a single `get_weather` activity created:
+
+![Weather Activity](../_images/weather_activity_tool.png)
+
+The activity shows the external call with retry capability. Each step (model invocation → tool call → model invocation) is durable.
+
+### Pattern 2: Multi-Activity Tool (Optional)
+
+To try the advanced banking example, uncomment the `move_money` sections in the code, then ask to move money.
+
+1. Check the agent response:
 
-**Pattern 2 (commented out in code):** Uncomment the `move_money` section, then ask to move money
-- See TWO sequential activities: `withdraw_money` → `deposit_money`
-- If the system crashes after withdraw but before deposit, Temporal resumes exactly where it left off
-- The deposit will still happen - guaranteed transactional integrity
+![Money Transfer Response](../_images/move_money_response.png)
+
+2. Open Temporal UI and see TWO sequential activities:
+
+![Money Transfer Workflow](../_images/move_money_temporal.png)
+
+- First: `withdraw_money` activity executes
+- Then: `deposit_money` activity executes
+- Each activity shows its parameters and execution time
+
+**Critical insight:** If the system crashes after withdraw but before deposit, Temporal resumes exactly where it left off. The deposit will still happen - guaranteed transactional integrity.
 
 ## Key Code
 
+### Pattern 1: Single Activity Tool
 ```python
-# Pattern 1: Direct activity conversion
+# Define the activity
+@activity.defn
+async def get_weather(city: str) -> str:
+    """Get the weather for a given city"""
+    # This could be an API call - Temporal handles retries
+    return f"The weather in {city} is sunny"
+
+# Use activity_as_tool to convert it
 weather_agent = Agent(
+    name="Weather Assistant",
+    instructions="Use the get_weather tool to answer weather questions.",
     tools=[
         activity_as_tool(get_weather, start_to_close_timeout=timedelta(seconds=10))
     ]
 )
+```
 
-# Pattern 2: Function tool coordinating multiple activities (see code for full example)
-# The tool internally calls workflow.start_activity_method() multiple times
-# guaranteeing the sequence and making each step durable
+### Pattern 2: Multi-Activity Tool
+```python
+# Define individual activities
+@activity.defn
+async def withdraw_money(from_account: str, amount: float) -> str:
+    # Simulate API call
+    await asyncio.sleep(5)
+    return f"Withdrew ${amount} from {from_account}"
+
+@activity.defn
+async def deposit_money(to_account: str, amount: float) -> str:
+    # Simulate API call
+    await asyncio.sleep(10)
+    return f"Deposited ${amount} into {to_account}"
+
+# Create a function tool that orchestrates both activities
+@function_tool
+async def move_money(from_account: str, to_account: str, amount: float) -> str:
+    """Move money from one account to another"""
+
+    # Step 1: Withdraw (becomes an activity)
+    await workflow.start_activity(
+        "withdraw_money",
+        args=[from_account, amount],
+        start_to_close_timeout=timedelta(days=1)
+    )
+
+    # Step 2: Deposit (becomes an activity)
+    await workflow.start_activity(
+        "deposit_money",
+        args=[to_account, amount],
+        start_to_close_timeout=timedelta(days=1)
+    )
+
+    return "Money transferred successfully"
+
+# Use the tool in your agent
+money_agent = Agent(
+    name="Money Mover",
+    instructions="Use move_money to transfer funds between accounts.",
+    tools=[move_money]
+)
 ```
 
+## When to Use Each Pattern
+
+### Use Pattern 1 when:
+- Tool performs a single external operation (API call, DB query)
+- Operation is already idempotent
+- No sequencing guarantees needed
+
+### Use Pattern 2 when:
+- Tool requires multiple sequential operations
+- Order must be guaranteed (withdraw THEN deposit)
+- Operations need to be atomic from the agent's perspective
+- You want transactional integrity across steps
+
 ## Why This Matters
 
 **Without Temporal:** If you withdraw money but crash before depositing, you're stuck in a broken state. The money is gone from the source account with no way to recover.
 
-**With Temporal:** Guaranteed execution with exact resumption after failures. Either both operations complete, or the workflow can handle partial completion. This is what makes agents production-ready for real-world operations like financial transactions, order fulfillment, or any multi-step process.
+**With Temporal (Pattern 2):**
+- Guaranteed execution with exact resumption after failures
+- If the system crashes after withdraw, Temporal resumes and completes deposit
+- Each step is tracked and retried independently
+- Full observability of the entire operation
+
+**Key insight:** Pattern 2 moves sequencing control from the LLM (which might call tools in wrong order) to your deterministic code (which guarantees correct order). The LLM still decides *when* to call the tool, but your code controls *how* the operations execute.
 
-**Key insight:** Pattern 2 moves sequencing control from the LLM (which might call tools in wrong order) to your deterministic code (which guarantees correct order).
+This makes agents production-ready for:
+- Financial transactions
+- Order fulfillment workflows
+- Multi-step API integrations
+- Any operation where partial completion is dangerous
diff --git a/examples/tutorials/10_agentic/10_temporal/080_open_ai_agents_sdk_human_in_the_loop/README.md b/examples/tutorials/10_agentic/10_temporal/080_open_ai_agents_sdk_human_in_the_loop/README.md
