Merge branch 'main' into bugfixed-unhandled-reasoning-content

Author: ygbingo

.github/codex/home/config.toml

@@ -0,0 +1 @@
+model = "o3"

.github/codex/labels/codex-attempt.md

@@ -0,0 +1,9 @@
+Attempt to solve the reported issue.
+
+If a code change is required, create a new branch, commit the fix, and open a pull request that resolves the problem.
+
+Here is the original GitHub issue that triggered this run:
+
+### {CODEX_ACTION_ISSUE_TITLE}
+
+{CODEX_ACTION_ISSUE_BODY}

.github/codex/labels/codex-review.md

@@ -0,0 +1,7 @@
+Review this PR and respond with a very concise final message, formatted in Markdown.
+
+There should be a summary of the changes (1-2 sentences) and a few bullet points if necessary.
+
+Then provide the **review** (1-2 sentences plus bullet points, friendly tone).
+
+{CODEX_ACTION_GITHUB_EVENT_PATH} contains the JSON that triggered this GitHub workflow. It contains the `base` and `head` refs that define this PR. Both refs are available locally.

.github/codex/labels/codex-triage.md

@@ -0,0 +1,7 @@
+Troubleshoot whether the reported issue is valid.
+
+Provide a concise and respectful comment summarizing the findings.
+
+### {CODEX_ACTION_ISSUE_TITLE}
+
+{CODEX_ACTION_ISSUE_BODY}

.github/workflows/codex.yml

@@ -0,0 +1,60 @@
+name: Codex
+
+on:
+  issues:
+    types: [opened, labeled]
+  pull_request:
+    branches: [main]
+    types: [labeled]
+
+jobs:
+  codex:
+    # This `if` check provides complex filtering logic to avoid running Codex
+    # on every PR. Admittedly, one thing this does not verify is whether the
+    # sender has write access to the repo: that must be done as part of a
+    # runtime step.
+    #
+    # Note the label values should match the ones in the .github/codex/labels
+    # folder.
+    if: |
+      (github.event_name == 'issues' && (
+        (github.event.action == 'labeled' && (github.event.label.name == 'codex-attempt' || github.event.label.name == 'codex-triage'))
+      )) ||
+      (github.event_name == 'pull_request' && github.event.action == 'labeled' && github.event.label.name == 'codex-review')
+    runs-on: ubuntu-latest
+    permissions:
+      contents: write # can push or create branches
+      issues: write # for comments + labels on issues/PRs
+      pull-requests: write # for PR comments/labels
+    steps:
+      # TODO: Consider adding an optional mode (--dry-run?) to actions/codex
+      # that verifies whether Codex should actually be run for this event.
+      # (For example, it may be rejected because the sender does not have
+      # write access to the repo.) The benefit would be two-fold:
+      # 1. As the first step of this job, it gives us a chance to add a reaction
+      #    or comment to the PR/issue ASAP to "ack" the request.
+      # 2. It saves resources by skipping the clone and setup steps below if
+      #    Codex is not going to run.
+
+      - name: Checkout repository
+        uses: actions/checkout@v4
+
+      # We install the dependencies like we would for an ordinary CI job,
+      # particularly because Codex will not have network access to install
+      # these dependencies.
+      - name: Setup uv
+        uses: astral-sh/setup-uv@v5
+        with:
+          enable-cache: true
+
+      - name: Install dependencies
+        run: make sync
+
+      # Note it is possible that the `verify` step internal to Run Codex will
+      # fail, in which case the work to setup the repo was worthless :(
+      - name: Run Codex
+        uses: openai/codex/.github/actions/codex@main
+        with:
+          openai_api_key: ${{ secrets.PROD_OPENAI_API_KEY }}
+          github_token: ${{ secrets.GITHUB_TOKEN }}
+          codex_home: ./.github/codex/home

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
@@ -296,6 +299,7 @@ make format-check # run style checker
 We'd like to acknowledge the excellent work of the open-source community, especially:
 
 -   [Pydantic](https://docs.pydantic.dev/latest/) (data validation) and [PydanticAI](https://ai.pydantic.dev/) (advanced agent framework)
+-   [LiteLLM](https://github.com/BerriAI/litellm) (unified interface for 100+ LLMs)
 -   [MkDocs](https://github.com/squidfunk/mkdocs-material)
 -   [Griffe](https://github.com/mkdocstrings/griffe)
 -   [uv](https://github.com/astral-sh/uv) and [ruff](https://github.com/astral-sh/ruff)

docs/agents.md

@@ -16,6 +16,7 @@ from agents import Agent, ModelSettings, function_tool
 
 @function_tool
 def get_weather(city: str) -> str:
+     """returns weather info for the specified city."""
     return f"The weather in {city} is sunny"
 
 agent = Agent(