update README files

Author: jssmith

openai_agents/README.md

@@ -21,66 +21,20 @@ 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/basic/run_worker.py
-   ```
+Each directory contains a complete example with its own README for detailed instructions:
 
-2. **Run individual samples** in separate terminals:
+### [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.
 
-### Basic Agent Examples
+### [Agent Patterns](./agent_patterns/README.md)
+Advanced patterns for agent composition, including using agents as tools within other agents.
 
-- **Hello World Agent** - Simple agent that responds in haikus:
-  ```bash
-  uv run openai_agents/basic/run_hello_world_workflow.py
-  ```
+### [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.
 
-- **Tools Agent** - Agent with access to external tools (weather API):
-  ```bash
-  uv run openai_agents/basic/run_tools_workflow.py
-  ```
-
-### Agent Patterns
-
-Start the worker:
-
-   ```bash
-   uv run openai_agents/agent_patterns/run_worker.py
-   ```
-
-- **Agents as Tools** - Demonstrate using agents as tools within other agents:
-
-  ```bash
-  uv run openai_agents/agent_patterns/run_agents_as_tools_workflow.py
-  ```
-
-### Advanced Multi-Agent Examples
-
-- **Research Workflow** - Multi-agent research system with specialized roles:
-
-  Start the worker:
-
-   ```bash
-   uv run openai_agents/research_bot/run_worker.py
-   ```
-
-  ```bash
-  uv run openai_agents/research_bot/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):
-
-  Start the worker:
-
-   ```bash
-   uv run openai_agents/customer_service/run_worker.py
-   ```
-
-  ```bash
-  uv run openai_agents/customer_service/run_customer_service_client.py --conversation-id my-conversation-123
-  ```
+### [Customer Service](./customer_service/README.md)
+Interactive customer service agent with escalation capabilities, demonstrating conversational workflows.
 
 

openai_agents/agent_patterns/README.md

@@ -0,0 +1,68 @@
+# 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)*
+
+## 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
+
+**TODO**
+
+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. Generate the story
+3. Generate the ending
+
+Each of these steps can be performed by an agent. The output of one agent is used as input to the next.
+
+## Handoffs and Routing
+
+**TODO**
+
+In many situations, you have specialized sub-agents that handle specific tasks. You can use handoffs to route the task to the right agent.
+
+For example, you might have a frontline agent that receives a request, and then hands off to a specialized agent based on the language of the request.
+
+## 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.
+
+For example, you could model a translation task as tool calls instead: rather than handing over to the language-specific agent, you could call the agent as a tool, and then use the result in the next step. This enables things like translating multiple languages at once.
+
+```bash
+uv run openai_agents/agent_patterns/run_agents_as_tools_workflow.py
+```
+
+## LLM-as-a-Judge
+
+**TODO**
+
+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.
+
+For example, you could use an LLM to generate an outline for a story, and then use a second LLM to evaluate the outline and provide feedback. You can then use the feedback to improve the outline, and repeat until the LLM is satisfied with the outline.
+
+## Parallelization
+
+**TODO**
+
+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.
+
+## Guardrails
+
+**TODO**
+
+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.

openai_agents/basic/README.md

@@ -0,0 +1,25 @@
+# Basic Agent Examples
+
+Simple examples to get started with OpenAI Agents SDK integrated with Temporal workflows.
+
+*Adapted from [OpenAI Agents SDK basic examples](https://github.com/openai/openai-agents-python/tree/main/examples/basic)*
+
+## Running the Examples
+
+First, start the worker (supports all basic examples):
+```bash
+uv run openai_agents/basic/run_worker.py
+```
+
+Then run individual examples in separate terminals:
+
+### Hello World Agent
+```bash
+uv run openai_agents/basic/run_hello_world_workflow.py
+```
+
+### Tools Agent
+Agent with access to external tools (weather API):
+```bash
+uv run openai_agents/basic/run_tools_workflow.py
+```

openai_agents/customer_service/README.md

@@ -0,0 +1,21 @@
+# Customer Service
+
+Interactive customer service agent with escalation capabilities, extended with Temporal's durable conversational workflows.
+
+*Adapted from [OpenAI Agents SDK customer service](https://github.com/openai/openai-agents-python/tree/main/examples/customer_service)*
+
+This example demonstrates how to build persistent, stateful conversations where each conversation maintains state across multiple interactions and can survive system restarts and failures.
+
+## Running the Example
+
+First, start the worker:
+```bash
+uv run openai_agents/customer_service/run_worker.py
+```
+
+Then start a customer service conversation:
+```bash
+uv run openai_agents/customer_service/run_customer_service_client.py --conversation-id my-conversation-123
+```
+
+You can start a new conversation with any unique conversation ID, or resume existing conversations by using the same conversation ID. The conversation state is persisted in the Temporal workflow, allowing you to resume conversations even after restarting the client.

openai_agents/research_bot/README.md

@@ -0,0 +1,35 @@
+# Research Bot
+
+Multi-agent research system with specialized roles, extended with Temporal's durable execution.
+
+*Adapted from [OpenAI Agents SDK research bot](https://github.com/openai/openai-agents-python/tree/main/examples/research_bot)*
+
+## Architecture
+
+The flow is:
+
+1. User enters their research topic
+2. `planner_agent` comes up with a plan to search the web for information. The plan is a list of search queries, with a search term and a reason for each query.
+3. For each search item, we run a `search_agent`, which uses the Web Search tool to search for that term and summarize the results. These all run in parallel.
+4. Finally, the `writer_agent` receives the search summaries, and creates a written report.
+
+## Running the Example
+
+First, start the worker:
+```bash
+uv run openai_agents/research_bot/run_worker.py
+```
+
+Then run the research workflow:
+```bash
+uv run openai_agents/research_bot/run_research_workflow.py
+```
+
+## Suggested Improvements
+
+If you're building your own research bot, some ideas to add to this are:
+
+1. Retrieval: Add support for fetching relevant information from a vector store. You could use the File Search tool for this.
+2. Image and file upload: Allow users to attach PDFs or other files, as baseline context for the research.
+3. More planning and thinking: Models often produce better results given more time to think. Improve the planning process to come up with a better plan, and add an evaluation step so that the model can choose to improve its results, search for more stuff, etc.
+4. Code execution: Allow running code, which is useful for data analysis.