add examples section to docs

docs/examples.md

@@ -0,0 +1,33 @@
+# Examples
+
+Check out a variety of sample implementations of the SDK in the examples section of the [repo](https://github.com/openai/openai-agents-python/tree/main/examples). The examples are organized into several categories that demonstrate different patterns and capabilities.
+
+
+## Categories
+
+- **agent_patterns**
+  Examples in this category illustrate common agent design patterns, such as:
+  - Deterministic workflows
+  - Agents as tools
+  - Parallel agent execution
+
+- **basic**
+  These examples showcase foundational capabilities of the SDK, such as:
+  - Dynamic system prompts
+  - Streaming outputs
+  - Lifecycle events
+
+- **tool examples**
+  Learn how to implement OAI hosted tools such as web search and file search,
+   and integrate them into your agents.
+
+- **model providers**
+  Explore how to use non-OpenAI models with the SDK.
+
+- **handoffs**
+  See practical examples of agent handoffs.
+
+- **customer_service & research_bot**
+  Two more built-out examples that illustrate real-world applications:
+  - **customer_service**: Example customer service system for an airline.
+  - **research_bot**: Simple deep research clone.

mkdocs.yml

@@ -21,6 +21,7 @@ theme:
 nav:
     - Intro: index.md
     - Quickstart: quickstart.md
+    - Examples: examples.md
     - Documentation:
           - agents.md
           - running_agents.md