Merge branch 'openai:main' into main

Author: DanielHashmi

.github/workflows/update-docs.yml

@@ -0,0 +1,60 @@
+name: "Update Translated Docs"
+
+# This GitHub Actions job automates the process of updating all translated document pages. Please note the following:
+# 1. The translation results may vary each time; some differences in detail are expected.
+# 2. When you add a new page to the left-hand menu, **make sure to manually update mkdocs.yml** to include the new item.
+# 3. If you switch to a different LLM (for example, from o3 to a newer model), be sure to conduct thorough testing before making the switch.
+
+on:
+  push:
+    branches:
+      - main
+    paths:
+      - 'docs/**'
+      - mkdocs.yml
+
+jobs:
+  update-docs:
+    if: "!contains(github.event.head_commit.message, 'Update all translated document pages')"
+    name: Build and Push Translated Docs
+    runs-on: ubuntu-latest
+    timeout-minutes: 20
+    env:
+      PROD_OPENAI_API_KEY: ${{ secrets.PROD_OPENAI_API_KEY }}
+    steps:
+      - name: Checkout repository
+        uses: actions/checkout@v3
+        with:
+          fetch-depth: 0
+      - name: Setup uv
+        uses: astral-sh/setup-uv@v5
+        with:
+          enable-cache: true
+      - name: Install dependencies
+        run: make sync
+      - name: Build full docs
+        run: make build-full-docs
+
+      - name: Commit changes
+        id: commit
+        run: |
+          git config user.name "github-actions[bot]"
+          git config user.email "github-actions[bot]@users.noreply.github.com"
+          git add docs/
+          if [ -n "$(git status --porcelain)" ]; then
+            git commit -m "Update all translated document pages"
+            echo "committed=true" >> "$GITHUB_OUTPUT"
+          else
+            echo "No changes to commit"
+            echo "committed=false" >> "$GITHUB_OUTPUT"
+          fi
+
+      - name: Create Pull Request
+        if: steps.commit.outputs.committed == 'true'
+        uses: peter-evans/create-pull-request@v6
+        with:
+          commit-message: "Update all translated document pages"
+          title: "Update all translated document pages"
+          body: "Automated update of translated documentation"
+          branch: update-translated-docs-${{ github.run_id }}
+          delete-branch: true

Makefile

@@ -44,6 +44,7 @@ old_version_tests:
 
 .PHONY: build-docs
 build-docs:
+	uv run docs/scripts/generate_ref_files.py
 	uv run mkdocs build
 
 .PHONY: build-full-docs

README.md

@@ -17,125 +17,19 @@ The OpenAI Agents SDK is a lightweight yet powerful framework for building multi
 
 Explore the [examples](examples) directory to see the SDK in action, and read our [documentation](https://openai.github.io/openai-agents-python/) for more details.
 
-## Sessions
-
-The Agents SDK provides built-in session memory to automatically maintain conversation history across multiple agent runs, eliminating the need to manually handle `.to_input_list()` between turns.
-
-### Quick start
-
-```python
-from agents import Agent, Runner, SQLiteSession
-
-# Create agent
-agent = Agent(
-    name="Assistant",
-    instructions="Reply very concisely.",
-)
-
-# Create a session instance
-session = SQLiteSession("conversation_123")
-
-# First turn
-result = await Runner.run(
-    agent,
-    "What city is the Golden Gate Bridge in?",
-    session=session
-)
-print(result.final_output)  # "San Francisco"
-
-# Second turn - agent automatically remembers previous context
-result = await Runner.run(
-    agent,
-    "What state is it in?",
-    session=session
-)
-print(result.final_output)  # "California"
-
-# Also works with synchronous runner
-result = Runner.run_sync(
-    agent,
-    "What's the population?",
-    session=session
-)
-print(result.final_output)  # "Approximately 39 million"
-```
-
-### Session options
-
--   **No memory** (default): No session memory when session parameter is omitted
--   **`session: Session = DatabaseSession(...)`**: Use a Session instance to manage conversation history
-
-```python
-from agents import Agent, Runner, SQLiteSession
-
-# Custom SQLite database file
-session = SQLiteSession("user_123", "conversations.db")
-agent = Agent(name="Assistant")
-
-# Different session IDs maintain separate conversation histories
-result1 = await Runner.run(
-    agent,
-    "Hello",
-    session=session
-)
-result2 = await Runner.run(
-    agent,
-    "Hello",
-    session=SQLiteSession("user_456", "conversations.db")
-)
-```
-
-### Custom session implementations
-
-You can implement your own session memory by creating a class that follows the `Session` protocol:
-
-```python
-from agents.memory import Session
-from typing import List
-
-class MyCustomSession:
-    """Custom session implementation following the Session protocol."""
-
-    def __init__(self, session_id: str):
-        self.session_id = session_id
-        # Your initialization here
-
-    async def get_items(self, limit: int | None = None) -> List[dict]:
-        # Retrieve conversation history for the session
-        pass
-
-    async def add_items(self, items: List[dict]) -> None:
-        # Store new items for the session
-        pass
-
-    async def pop_item(self) -> dict | None:
-        # Remove and return the most recent item from the session
-        pass
-
-    async def clear_session(self) -> None:
-        # Clear all items for the session
-        pass
-
-# Use your custom session
-agent = Agent(name="Assistant")
-result = await Runner.run(
-    agent,
-    "Hello",
-    session=MyCustomSession("my_session")
-)
-```
-
 ## Get started
 
 1. Set up your Python environment
 
-- Option A: Using venv (traditional method)
+-   Option A: Using venv (traditional method)
+
 ```bash
 python -m venv env
 source env/bin/activate  # On Windows: env\Scripts\activate
 ```
 
-- Option B: Using uv (recommended)
+-   Option B: Using uv (recommended)
+
 ```bash
 uv venv
 source .venv/bin/activate  # On Windows: .venv\Scripts\activate
@@ -263,6 +157,114 @@ The Agents SDK is designed to be highly flexible, allowing you to model a wide r
 
 The Agents SDK automatically traces your agent runs, making it easy to track and debug the behavior of your agents. Tracing is extensible by design, supporting custom spans and a wide variety of external destinations, including [Logfire](https://logfire.pydantic.dev/docs/integrations/llms/openai/#openai-agents), [AgentOps](https://docs.agentops.ai/v1/integrations/agentssdk), [Braintrust](https://braintrust.dev/docs/guides/traces/integrations#openai-agents-sdk), [Scorecard](https://docs.scorecard.io/docs/documentation/features/tracing#openai-agents-sdk-integration), and [Keywords AI](https://docs.keywordsai.co/integration/development-frameworks/openai-agent). For more details about how to customize or disable tracing, see [Tracing](http://openai.github.io/openai-agents-python/tracing), which also includes a larger list of [external tracing processors](http://openai.github.io/openai-agents-python/tracing/#external-tracing-processors-list).
 
+## Sessions
+
+The Agents SDK provides built-in session memory to automatically maintain conversation history across multiple agent runs, eliminating the need to manually handle `.to_input_list()` between turns.
+
+### Quick start
+
+```python
+from agents import Agent, Runner, SQLiteSession
+
+# Create agent
+agent = Agent(
+    name="Assistant",
+    instructions="Reply very concisely.",
+)
+
+# Create a session instance
+session = SQLiteSession("conversation_123")
+
+# First turn
+result = await Runner.run(
+    agent,
+    "What city is the Golden Gate Bridge in?",
+    session=session
+)
+print(result.final_output)  # "San Francisco"
+
+# Second turn - agent automatically remembers previous context
+result = await Runner.run(
+    agent,
+    "What state is it in?",
+    session=session
+)
+print(result.final_output)  # "California"
+
+# Also works with synchronous runner
+result = Runner.run_sync(
+    agent,
+    "What's the population?",
+    session=session
+)
+print(result.final_output)  # "Approximately 39 million"
+```
+
+### Session options
+
+-   **No memory** (default): No session memory when session parameter is omitted
+-   **`session: Session = DatabaseSession(...)`**: Use a Session instance to manage conversation history
+
+```python
+from agents import Agent, Runner, SQLiteSession
+
+# Custom SQLite database file
+session = SQLiteSession("user_123", "conversations.db")
+agent = Agent(name="Assistant")
+
+# Different session IDs maintain separate conversation histories
+result1 = await Runner.run(
+    agent,
+    "Hello",
+    session=session
+)
+result2 = await Runner.run(
+    agent,
+    "Hello",
+    session=SQLiteSession("user_456", "conversations.db")
+)
+```
+
+### Custom session implementations
+
+You can implement your own session memory by creating a class that follows the `Session` protocol:
+
+```python
+from agents.memory import Session
+from typing import List
+
+class MyCustomSession:
+    """Custom session implementation following the Session protocol."""
+
+    def __init__(self, session_id: str):
+        self.session_id = session_id
+        # Your initialization here
+
+    async def get_items(self, limit: int | None = None) -> List[dict]:
+        # Retrieve conversation history for the session
+        pass
+
+    async def add_items(self, items: List[dict]) -> None:
+        # Store new items for the session
+        pass
+
+    async def pop_item(self) -> dict | None:
+        # Remove and return the most recent item from the session
+        pass
+
+    async def clear_session(self) -> None:
+        # Clear all items for the session
+        pass
+
+# Use your custom session
+agent = Agent(name="Assistant")
+result = await Runner.run(
+    agent,
+    "Hello",
+    session=MyCustomSession("my_session")
+)
+```
+
 ## Development (only needed if you need to edit the SDK/examples)
 
 0. Ensure you have [`uv`](https://docs.astral.sh/uv/) installed.
@@ -284,6 +286,7 @@ make check # run tests linter and typechecker
 ```
 
 Or to run them individually:
+
 ```
 make tests  # run tests
 make mypy   # run typechecker