Merge branch 'main' into env_config_sample

Author: THardy98

openai_agents/README.md

@@ -1,6 +1,6 @@
 # Temporal OpenAI Agents SDK Integration
 
-⚠️ **Experimental** - This module is not yet stable and may change in the future.
+⚠️ **Public Preview** - This integration is experimental and its interfaces may change prior to General Availability.
 
 This directory contains samples demonstrating how to use the [OpenAI Agents SDK](https://github.com/openai/openai-agents-python) with Temporal's durable execution engine.
 These samples are adapted from the [OpenAI Agents SDK examples](https://github.com/openai/openai-agents-python/tree/main/examples) and extended with Temporal's durability and orchestration capabilities.
@@ -21,42 +21,18 @@ This approach ensures that AI agent workflows are durable, observable, and can h
 - Required dependencies installed via `uv sync --group openai-agents`
 - OpenAI API key set as environment variable: `export OPENAI_API_KEY=your_key_here`
 
-## Running the Examples
+## Examples
 
-1. **Start the worker** (supports all samples):
-   ```bash
-   uv run openai_agents/run_worker.py
-   ```
+Each directory contains a complete example with its own README for detailed instructions:
 
-2. **Run individual samples** in separate terminals:
-
-### Basic Agent Examples
-
-- **Hello World Agent** - Simple agent that responds in haikus:
-  ```bash
-  uv run openai_agents/run_hello_world_workflow.py
-  ```
-
-- **Tools Agent** - Agent with access to external tools (weather API):
-  ```bash
-  uv run openai_agents/run_tools_workflow.py
-  ```
-
-### Advanced Multi-Agent Examples
-
-- **Research Workflow** - Multi-agent research system with specialized roles:
-  ```bash
-  uv run openai_agents/run_research_workflow.py
-  ```
-  Features a planner agent, search agent, and writer agent working together.
-
-- **Customer Service Workflow** - Customer service agent with escalation capabilities (interactive):
-  ```bash
-  uv run openai_agents/run_customer_service_client.py --conversation-id my-conversation-123
-  ```
-
-- **Agents as Tools** - Demonstrate using agents as tools within other agents:
-  ```bash
-  uv run openai_agents/run_agents_as_tools_workflow.py
-  ```
+- **[Basic Examples](./basic/README.md)** - Simple agent examples including a hello world agent and a tools-enabled agent that can access external APIs like weather services.
+- **[Agent Patterns](./agent_patterns/README.md)** - Advanced patterns for agent composition, including using agents as tools within other agents.
+- **[Tools](./tools/README.md)** - Demonstrates available tools such as file search, image generation, and others.
+- **[Handoffs](./handoffs/README.md)** - Agents collaborating via handoffs.
+- **[Hosted MCP](./hosted_mcp/README.md)** - Using the MCP client functionality of the OpenAI Responses API.
+- **[Model Providers](./model_providers/README.md)** - Using custom LLM providers (e.g., Anthropic via LiteLLM).
+- **[Research Bot](./research_bot/README.md)** - Multi-agent research system with specialized roles: a planner agent, search agent, and writer agent working together to conduct comprehensive research.
+- **[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.
 

openai_agents/agent_patterns/README.md

@@ -0,0 +1,97 @@
+# Agent Patterns
+
+Common agentic patterns extended with Temporal's durable execution capabilities.
+
+*Adapted from [OpenAI Agents SDK agent patterns](https://github.com/openai/openai-agents-python/tree/main/examples/agent_patterns)*
+
+Before running these examples, be sure to review the [prerequisites and background on the integration](../README.md).
+
+## Running the Examples
+
+First, start the worker (supports all patterns):
+```bash
+uv run openai_agents/agent_patterns/run_worker.py
+```
+
+Then run individual examples in separate terminals:
+
+### Deterministic Flows
+Sequential agent execution with validation gates - demonstrates breaking complex tasks into smaller steps:
+```bash
+uv run openai_agents/agent_patterns/run_deterministic_workflow.py
+```
+
+### Parallelization
+Run multiple agents in parallel and select the best result - useful for improving quality or reducing latency:
+```bash
+uv run openai_agents/agent_patterns/run_parallelization_workflow.py
+```
+
+### LLM-as-a-Judge
+Iterative improvement using feedback loops - generate content, evaluate it, and improve until satisfied:
+```bash
+uv run openai_agents/agent_patterns/run_llm_as_a_judge_workflow.py
+```
+
+### Agents as Tools
+Use agents as callable tools within other agents - enables composition and specialized task delegation:
+```bash
+uv run openai_agents/agent_patterns/run_agents_as_tools_workflow.py
+```
+
+### Agent Routing and Handoffs
+Route requests to specialized agents based on content analysis (adapted for non-streaming):
+```bash
+uv run openai_agents/agent_patterns/run_routing_workflow.py
+```
+
+### Input Guardrails
+Pre-execution validation to prevent unwanted requests - demonstrates safety mechanisms:
+```bash
+uv run openai_agents/agent_patterns/run_input_guardrails_workflow.py
+```
+
+### Output Guardrails
+Post-execution validation to detect sensitive content - ensures safe responses:
+```bash
+uv run openai_agents/agent_patterns/run_output_guardrails_workflow.py
+```
+
+### Forcing Tool Use
+Control tool execution strategies - choose between different approaches to tool usage:
+```bash
+uv run openai_agents/agent_patterns/run_forcing_tool_use_workflow.py
+```
+
+## Pattern Details
+
+### Deterministic Flows
+A common tactic is to break down a task into a series of smaller steps. Each task can be performed by an agent, and the output of one agent is used as input to the next. For example, if your task was to generate a story, you could break it down into the following steps:
+
+1. Generate an outline
+2. Check outline quality and genre
+3. Write the story (only if outline passes validation)
+
+Each of these steps can be performed by an agent. The output of one agent is used as input to the next.
+
+### Parallelization
+Running multiple agents in parallel is a common pattern. This can be useful for both latency (e.g. if you have multiple steps that don't depend on each other) and also for other reasons e.g. generating multiple responses and picking the best one.
+
+### LLM-as-a-Judge
+LLMs can often improve the quality of their output if given feedback. A common pattern is to generate a response using a model, and then use a second model to provide feedback. You can even use a small model for the initial generation and a larger model for the feedback, to optimize cost.
+
+### Agents as Tools
+The mental model for handoffs is that the new agent "takes over". It sees the previous conversation history, and owns the conversation from that point onwards. However, this is not the only way to use agents. You can also use agents as a tool - the tool agent goes off and runs on its own, and then returns the result to the original agent.
+
+### Guardrails
+Related to parallelization, you often want to run input guardrails to make sure the inputs to your agents are valid. For example, if you have a customer support agent, you might want to make sure that the user isn't trying to ask for help with a math problem.
+
+You can definitely do this without any special Agents SDK features by using parallelization, but we support a special guardrail primitive. Guardrails can have a "tripwire" - if the tripwire is triggered, the agent execution will immediately stop and a `GuardrailTripwireTriggered` exception will be raised.
+
+This is really useful for latency: for example, you might have a very fast model that runs the guardrail and a slow model that runs the actual agent. You wouldn't want to wait for the slow model to finish, so guardrails let you quickly reject invalid inputs.
+
+## Omitted Examples
+
+The following patterns from the [reference repository](https://github.com/openai/openai-agents-python/tree/main/examples/agent_patterns) are not included in this Temporal adaptation:
+
+- **Streaming Guardrails**: Requires streaming capabilities which are not yet available in the Temporal integration

openai_agents/agent_patterns/run_agents_as_tools_workflow.py

@@ -0,0 +1,32 @@
+import asyncio
+
+from temporalio.client import Client
+from temporalio.contrib.openai_agents import OpenAIAgentsPlugin
+
+from openai_agents.agent_patterns.workflows.agents_as_tools_workflow import (
+    AgentsAsToolsWorkflow,
+)
+
+
+async def main():
+    # Create client connected to server at the given address
+    client = await Client.connect(
+        "localhost:7233",
+        plugins=[
+            OpenAIAgentsPlugin(),
+        ],
+    )
+
+    # Execute a workflow
+    result = await client.execute_workflow(
+        AgentsAsToolsWorkflow.run,
+        "Please translate 'Good morning, how are you?' to Spanish and French",
+        id="agents-as-tools-workflow-example",
+        task_queue="openai-agents-patterns-task-queue",
+    )
+
+    print(f"Result: {result}")
+
+
+if __name__ == "__main__":
+    asyncio.run(main())

openai_agents/agent_patterns/run_deterministic_workflow.py

@@ -0,0 +1,31 @@
+import asyncio
+
+from temporalio.client import Client
+from temporalio.contrib.openai_agents import OpenAIAgentsPlugin
+
+from openai_agents.agent_patterns.workflows.deterministic_workflow import (
+    DeterministicWorkflow,
+)
+
+
+async def main():
+    # Create client connected to server at the given address
+    client = await Client.connect(
+        "localhost:7233",
+        plugins=[
+            OpenAIAgentsPlugin(),
+        ],
+    )
+
+    # Execute a workflow
+    result = await client.execute_workflow(
+        DeterministicWorkflow.run,
+        "Write a science fiction story about time travel",
+        id="deterministic-workflow-example",
+        task_queue="openai-agents-patterns-task-queue",
+    )
+    print(f"Result: {result}")
+
+
+if __name__ == "__main__":
+    asyncio.run(main())

openai_agents/agent_patterns/run_forcing_tool_use_workflow.py

@@ -0,0 +1,50 @@
+import asyncio
+
+from temporalio.client import Client
+from temporalio.contrib.openai_agents import OpenAIAgentsPlugin
+
+from openai_agents.agent_patterns.workflows.forcing_tool_use_workflow import (
+    ForcingToolUseWorkflow,
+)
+
+
+async def main():
+    # Create client connected to server at the given address
+    client = await Client.connect(
+        "localhost:7233",
+        plugins=[
+            OpenAIAgentsPlugin(),
+        ],
+    )
+
+    # Execute workflows with different tool use behaviors
+    print("Testing default behavior:")
+    result1 = await client.execute_workflow(
+        ForcingToolUseWorkflow.run,
+        "default",
+        id="forcing-tool-use-workflow-default",
+        task_queue="openai-agents-patterns-task-queue",
+    )
+    print(f"Default result: {result1}")
+
+    print("\nTesting first_tool behavior:")
+    result2 = await client.execute_workflow(
+        ForcingToolUseWorkflow.run,
+        "first_tool",
+        id="forcing-tool-use-workflow-first-tool",
+        task_queue="openai-agents-patterns-task-queue",
+    )
+    print(f"First tool result: {result2}")
+
+    print("\nTesting custom behavior:")
+    result3 = await client.execute_workflow(
+        ForcingToolUseWorkflow.run,
+        "custom",
+        id="forcing-tool-use-workflow-custom",
+        task_queue="openai-agents-patterns-task-queue",
+    )
+    print(f"Custom result: {result3}")
+
+
+if __name__ == "__main__":
+    asyncio.run(main())

openai_agents/agent_patterns/run_input_guardrails_workflow.py

@@ -0,0 +1,40 @@
+import asyncio
+
+from temporalio.client import Client
+from temporalio.contrib.openai_agents import OpenAIAgentsPlugin
+
+from openai_agents.agent_patterns.workflows.input_guardrails_workflow import (
+    InputGuardrailsWorkflow,
+)
+
+
+async def main():
+    # Create client connected to server at the given address
+    client = await Client.connect(
+        "localhost:7233",
+        plugins=[
+            OpenAIAgentsPlugin(),
+        ],
+    )
+
+    # Execute a workflow with a normal question (should pass)
+    result1 = await client.execute_workflow(
+        InputGuardrailsWorkflow.run,
+        "What's the capital of California?",
+        id="input-guardrails-workflow-normal",
+        task_queue="openai-agents-patterns-task-queue",
+    )
+    print(f"Normal question result: {result1}")
+
+    # Execute a workflow with a math homework question (should be blocked)
+    result2 = await client.execute_workflow(
+        InputGuardrailsWorkflow.run,
+        "Can you help me solve for x: 2x + 5 = 11?",
+        id="input-guardrails-workflow-blocked",
+        task_queue="openai-agents-patterns-task-queue",
+    )
+    print(f"Math homework result: {result2}")
+
+
+if __name__ == "__main__":
+    asyncio.run(main())

openai_agents/agent_patterns/run_llm_as_a_judge_workflow.py

@@ -0,0 +1,31 @@
+import asyncio
+
+from temporalio.client import Client
+from temporalio.contrib.openai_agents import OpenAIAgentsPlugin
+
+from openai_agents.agent_patterns.workflows.llm_as_a_judge_workflow import (
+    LLMAsAJudgeWorkflow,
+)
+
+
+async def main():
+    # Create client connected to server at the given address
+    client = await Client.connect(
+        "localhost:7233",
+        plugins=[
+            OpenAIAgentsPlugin(),
+        ],
+    )
+
+    # Execute a workflow
+    result = await client.execute_workflow(
+        LLMAsAJudgeWorkflow.run,
+        "A thrilling adventure story about pirates searching for treasure",
+        id="llm-as-a-judge-workflow-example",
+        task_queue="openai-agents-patterns-task-queue",
+    )
+    print(f"Result: {result}")
+
+
+if __name__ == "__main__":
+    asyncio.run(main())

openai_agents/agent_patterns/run_output_guardrails_workflow.py

@@ -0,0 +1,40 @@
+import asyncio
+
+from temporalio.client import Client
+from temporalio.contrib.openai_agents import OpenAIAgentsPlugin
+
+from openai_agents.agent_patterns.workflows.output_guardrails_workflow import (
+    OutputGuardrailsWorkflow,
+)
+
+
+async def main():
+    # Create client connected to server at the given address
+    client = await Client.connect(
+        "localhost:7233",
+        plugins=[
+            OpenAIAgentsPlugin(),
+        ],
+    )
+
+    # Execute a workflow with a normal question (should pass)
+    result1 = await client.execute_workflow(
+        OutputGuardrailsWorkflow.run,
+        "What's the capital of California?",
+        id="output-guardrails-workflow-normal",
+        task_queue="openai-agents-patterns-task-queue",
+    )
+    print(f"Normal question result: {result1}")
+
+    # Execute a workflow with input that might trigger sensitive data output
+    result2 = await client.execute_workflow(
+        OutputGuardrailsWorkflow.run,
+        "My phone number is 650-123-4567. Where do you think I live?",
+        id="output-guardrails-workflow-sensitive",
+        task_queue="openai-agents-patterns-task-queue",
+    )
+    print(f"Sensitive data result: {result2}")
+
+
+if __name__ == "__main__":
+    asyncio.run(main())