.github/ISSUE_TEMPLATE/feature_request.md

@@ -10,7 +10,7 @@ assignees: ''
 ### Please read this first
 
 - **Have you read the docs?**[Agents SDK docs](https://openai.github.io/openai-agents-python/)
-- **Have you searched for related issues?** Others may have had similar requesrs
+- **Have you searched for related issues?** Others may have had similar requests
 
 ### Describe the feature
 What is the feature you're requesting? How would it work? Please provide examples and details if possible.

.github/ISSUE_TEMPLATE/question.md

@@ -10,7 +10,7 @@ assignees: ''
 ### Please read this first
 
 - **Have you read the docs?**[Agents SDK docs](https://openai.github.io/openai-agents-python/)
-- **Have you searched for related issues?** Others may have had similar requesrs
+- **Have you searched for related issues?** Others may have had similar requests
 
 ### Question
 Describe your question. Provide details if available.

.github/workflows/tests.yml

@@ -5,8 +5,7 @@ on:
     branches:
       - main
   pull_request:
-    branches:
-      - main
+    # All PRs, including stacked PRs
 
 env:
   UV_FROZEN: "1"

.gitignore

@@ -141,4 +141,5 @@ cython_debug/
 .ruff_cache/
 
 # PyPI configuration file
-.pypirc
+.pypirc
+.aider*

.vscode/settings.json

@@ -0,0 +1,7 @@
+{
+    "python.testing.pytestArgs": [
+        "tests"
+    ],
+    "python.testing.unittestEnabled": false,
+    "python.testing.pytestEnabled": true
+}

AGENTS.md

@@ -0,0 +1,69 @@
+Welcome to the OpenAI Agents SDK repository. This file contains the main points for new contributors.
+
+## Repository overview
+
+- **Source code**: `src/agents/` contains the implementation.
+- **Tests**: `tests/` with a short guide in `tests/README.md`.
+- **Examples**: under `examples/`.
+- **Documentation**: markdown pages live in `docs/` with `mkdocs.yml` controlling the site.
+- **Utilities**: developer commands are defined in the `Makefile`.
+- **PR template**: `.github/PULL_REQUEST_TEMPLATE/pull_request_template.md` describes the information every PR must include.
+
+## Local workflow
+
+1. Format, lint and type‑check your changes:
+
+   ```bash
+   make format
+   make lint
+   make mypy
+   ```
+
+2. Run the tests:
+
+   ```bash
+   make tests
+   ```
+
+   To run a single test, use `uv run pytest -s -k <test_name>`.
+
+3. Build the documentation (optional but recommended for docs changes):
+
+   ```bash
+   make build-docs
+   ```
+
+   Coverage can be generated with `make coverage`.
+
+## Snapshot tests
+
+Some tests rely on inline snapshots. See `tests/README.md` for details on updating them:
+
+```bash
+make snapshots-fix      # update existing snapshots
+make snapshots-create   # create new snapshots
+```
+
+Run `make tests` again after updating snapshots to ensure they pass.
+
+## Style notes
+
+- Write comments as full sentences and end them with a period.
+
+## Pull request expectations
+
+PRs should use the template located at `.github/PULL_REQUEST_TEMPLATE/pull_request_template.md`. Provide a summary, test plan and issue number if applicable, then check that:
+
+- New tests are added when needed.
+- Documentation is updated.
+- `make lint` and `make format` have been run.
+- The full test suite passes.
+
+Commit messages should be concise and written in the imperative mood. Small, focused commits are preferred.
+
+## What reviewers look for
+
+- Tests covering new behaviour.
+- Consistent style: code formatted with `ruff format`, imports sorted, and type hints passing `mypy`.
+- Clear documentation for any public API changes.
+- Clean history and a helpful PR description.

Makefile

@@ -42,6 +42,11 @@ old_version_tests:
 build-docs:
 	uv run mkdocs build
 
+.PHONY: build-full-docs
+build-full-docs:
+	uv run docs/scripts/translate_docs.py
+	uv run mkdocs build
+
 .PHONY: serve-docs
 serve-docs:
 	uv run mkdocs serve

README.md

@@ -1,6 +1,6 @@
 # OpenAI Agents SDK
 
-The OpenAI Agents SDK is a lightweight yet powerful framework for building multi-agent workflows.
+The OpenAI Agents SDK is a lightweight yet powerful framework for building multi-agent workflows. It is provider-agnostic, supporting the OpenAI Responses and Chat Completions APIs, as well as 100+ other LLMs.
 
 <img src="https://cdn.openai.com/API/docs/images/orchestration.png" alt="Image of the Agents Tracing UI" style="max-height: 803px;">
 
@@ -13,8 +13,6 @@ 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.
 
-Notably, our SDK [is compatible](https://openai.github.io/openai-agents-python/models/) with any model providers that support the OpenAI Chat Completions API format.
-
 ## Get started
 
 1. Set up your Python environment

docs/agents.md

@@ -32,11 +32,11 @@ Agents are generic on their `context` type. Context is a dependency-injection to
 ```python
 @dataclass
 class UserContext:
-  uid: str
-  is_pro_user: bool
+    uid: str
+    is_pro_user: bool
 
-  async def fetch_purchases() -> list[Purchase]:
-     return ...
+    async def fetch_purchases() -> list[Purchase]:
+        return ...
 
 agent = Agent[UserContext](
     ...,

docs/config.md

@@ -63,7 +63,7 @@ Alternatively, you can customize the logs by adding handlers, filters, formatter
 ```python
 import logging
 
-logger =  logging.getLogger("openai.agents") # or openai.agents.tracing for the Tracing logger
+logger = logging.getLogger("openai.agents") # or openai.agents.tracing for the Tracing logger
 
 # To make all logs show up
 logger.setLevel(logging.DEBUG)

docs/examples.md

@@ -5,32 +5,38 @@ Check out a variety of sample implementations of the SDK in the examples section
 
 ## Categories
 
-- **agent_patterns:**
+- **[agent_patterns](https://github.com/openai/openai-agents-python/tree/main/examples/agent_patterns):**
   Examples in this category illustrate common agent design patterns, such as
-  
+
     - Deterministic workflows
     - Agents as tools
     - Parallel agent execution
 
-- **basic:**
+- **[basic](https://github.com/openai/openai-agents-python/tree/main/examples/basic):**
   These examples showcase foundational capabilities of the SDK, such as
-  
+
     - Dynamic system prompts
     - Streaming outputs
     - Lifecycle events
 
-- **tool examples:**
+- **[tool examples](https://github.com/openai/openai-agents-python/tree/main/examples/tools):**
   Learn how to implement OAI hosted tools such as web search and file search,
    and integrate them into your agents.
 
-- **model providers:**
+- **[model providers](https://github.com/openai/openai-agents-python/tree/main/examples/model_providers):**
   Explore how to use non-OpenAI models with the SDK.
 
-- **handoffs:**
+- **[handoffs](https://github.com/openai/openai-agents-python/tree/main/examples/handoffs):**
   See practical examples of agent handoffs.
 
-- **customer_service** and **research_bot:**
+- **[mcp](https://github.com/openai/openai-agents-python/tree/main/examples/mcp):**
+  Learn how to build agents with MCP.
+
+- **[customer_service](https://github.com/openai/openai-agents-python/tree/main/examples/customer_service)** and **[research_bot](https://github.com/openai/openai-agents-python/tree/main/examples/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.
+
+- **[voice](https://github.com/openai/openai-agents-python/tree/main/examples/voice):**
+  See examples of voice agents, using our TTS and STT models.

docs/ja/agents.md

@@ -0,0 +1,151 @@
+---
+search:
+  exclude: true
+---
+# エージェント
+
+エージェントはアプリの主要な構成ブロックです。エージェントは、大規模言語モデル ( LLM ) に instructions と tools を設定したものです。
+
+## 基本設定
+
+エージェントで最も一般的に設定するプロパティは次のとおりです。
+
+-   `instructions`: 開発者メッセージまたは system prompt とも呼ばれます。
+-   `model`: 使用する LLM と、temperature や top_p などのモデル調整パラメーターを指定する任意の `model_settings`。
+-   `tools`: エージェントがタスクを達成するために利用できるツール。
+
+```python
+from agents import Agent, ModelSettings, function_tool
+
+@function_tool
+def get_weather(city: str) -> str:
+    return f"The weather in {city} is sunny"
+
+agent = Agent(
+    name="Haiku agent",
+    instructions="Always respond in haiku form",
+    model="o3-mini",
+    tools=[get_weather],
+)
+```
+
+## コンテキスト
+
+エージェントはその `context` 型について汎用的です。コンテキストは依存性注入の手段で、`Runner.run()` に渡すオブジェクトです。これはすべてのエージェント、ツール、ハンドオフなどに渡され、エージェント実行時の依存関係や状態をまとめて保持します。任意の Python オブジェクトをコンテキストとして渡せます。
+
+```python
+@dataclass
+class UserContext:
+    uid: str
+    is_pro_user: bool
+
+    async def fetch_purchases() -> list[Purchase]:
+        return ...
+
+agent = Agent[UserContext](
+    ...,
+)
+```
+
+## 出力タイプ
+
+デフォルトでは、エージェントはプレーンテキスト ( つまり `str` ) を出力します。特定の型で出力させたい場合は `output_type` パラメーターを使用します。一般的には [Pydantic](https://docs.pydantic.dev/) オブジェクトを利用しますが、Pydantic の [TypeAdapter](https://docs.pydantic.dev/latest/api/type_adapter/) でラップ可能な型であれば何でも対応します。たとえば dataclass、list、TypedDict などです。
+
+```python
+from pydantic import BaseModel
+from agents import Agent
+
+
+class CalendarEvent(BaseModel):
+    name: str
+    date: str
+    participants: list[str]
+
+agent = Agent(
+    name="Calendar extractor",
+    instructions="Extract calendar events from text",
+    output_type=CalendarEvent,
+)
+```
+
+!!! note
+
+    `output_type` を渡すと、モデルは通常のプレーンテキスト応答の代わりに [structured outputs](https://platform.openai.com/docs/guides/structured-outputs) を使用するよう指示されます。
+
+## ハンドオフ
+
+ハンドオフは、エージェントが委譲できるサブエージェントです。ハンドオフのリストを渡しておくと、エージェントは必要に応じてそれらに処理を委譲できます。これにより、単一のタスクに特化したモジュール式エージェントを編成できる強力なパターンが実現します。詳細は [handoffs](handoffs.md) ドキュメントをご覧ください。
+
+```python
+from agents import Agent
+
+booking_agent = Agent(...)
+refund_agent = Agent(...)
+
+triage_agent = Agent(
+    name="Triage agent",
+    instructions=(
+        "Help the user with their questions."
+        "If they ask about booking, handoff to the booking agent."
+        "If they ask about refunds, handoff to the refund agent."
+    ),
+    handoffs=[booking_agent, refund_agent],
+)
+```
+
+## 動的 instructions
+
+通常はエージェント作成時に instructions を指定しますが、関数を介して動的に instructions を提供することもできます。その関数はエージェントとコンテキストを受け取り、プロンプトを返す必要があります。同期関数と `async` 関数の両方に対応しています。
+
+```python
+def dynamic_instructions(
+    context: RunContextWrapper[UserContext], agent: Agent[UserContext]
+) -> str:
+    return f"The user's name is {context.context.name}. Help them with their questions."
+
+
+agent = Agent[UserContext](
+    name="Triage agent",
+    instructions=dynamic_instructions,
+)
+```
+
+## ライフサイクルイベント (hooks)
+
+場合によっては、エージェントのライフサイクルを観察したいことがあります。たとえば、イベントをログに記録したり、特定のイベント発生時にデータを事前取得したりする場合です。`hooks` プロパティを使ってエージェントのライフサイクルにフックできます。[`AgentHooks`][agents.lifecycle.AgentHooks] クラスをサブクラス化し、関心のあるメソッドをオーバーライドしてください。
+
+## ガードレール
+
+ガードレールを使うと、エージェントの実行と並行してユーザー入力に対するチェックやバリデーションを実行できます。たとえば、ユーザーの入力内容が関連しているかをスクリーニングできます。詳細は [guardrails](guardrails.md) ドキュメントをご覧ください。
+
+## エージェントの複製
+
+`clone()` メソッドを使用すると、エージェントを複製し、必要に応じて任意のプロパティを変更できます。
+
+```python
+pirate_agent = Agent(
+    name="Pirate",
+    instructions="Write like a pirate",
+    model="o3-mini",
+)
+
+robot_agent = pirate_agent.clone(
+    name="Robot",
+    instructions="Write like a robot",
+)
+```
+
+## ツール使用の強制
+
+ツールの一覧を渡しても、LLM が必ずツールを使用するとは限りません。[`ModelSettings.tool_choice`][agents.model_settings.ModelSettings.tool_choice] を設定することでツール使用を強制できます。有効な値は次のとおりです。
+
+1. `auto` — ツールを使用するかどうかを LLM が判断します。
+2. `required` — LLM にツール使用を必須化します ( ただし使用するツールは自動選択 )。
+3. `none` — LLM にツールを使用しないことを要求します。
+4. 特定の文字列 ( 例: `my_tool` ) — その特定のツールを LLM に使用させます。
+
+!!! note
+
+    無限ループを防ぐため、フレームワークはツール呼び出し後に `tool_choice` を自動的に "auto" にリセットします。この動作は [`agent.reset_tool_choice`][agents.agent.Agent.reset_tool_choice] で設定できます。無限ループが起こる理由は、ツールの結果が LLM に送られ、`tool_choice` により再びツール呼び出しが生成される、という流れが繰り返されるからです。
+
+    ツール呼び出し後にエージェントを完全に停止させたい場合 ( auto モードで続行させたくない場合 ) は、[`Agent.tool_use_behavior="stop_on_first_tool"`] を設定してください。これにより、ツールの出力を LL M の追加処理なしにそのまま最終応答として返します。