Make docs and comments more consistent using Codex (#391)

Author: seratch

.changeset/nervous-windows-raise.md

@@ -0,0 +1,7 @@
+---
+"@openai/agents-core": patch
+"@openai/agents-realtime": patch
+"@openai/agents": patch
+---
+
+Make docs and comments more consistent using Codex

AGENTS.md

@@ -15,6 +15,7 @@ This guide helps new contributors get started with the OpenAI Agents JS monorepo
 7.  [Pull Request & Commit Guidelines](#pull-request--commit-guidelines)
 8.  [Review Process & What Reviewers Look For](#review-process--what-reviewers-look-for)
 9.  [Tips for Navigating the Repo](#tips-for-navigating-the-repo)
+10. [Prerequisites](#prerequisites)
 
 ## Overview
 
@@ -27,15 +28,15 @@ The OpenAI Agents JS repository is a pnpm-managed monorepo that provides:
 - `packages/agents-extensions`: Extensions for agent workflows.
 - `docs`: Documentation site powered by Astro.
 - `examples`: Sample projects demonstrating usage patterns.
-- `scripts`: Automation scripts (`dev.ts`, `embedMeta.ts`).
+- `scripts`: Automation scripts (`dev.mts`, `embedMeta.ts`).
 - `helpers`: Shared utilities for testing and other internal use.
 
 ## Repo Structure & Important Files
 
 - `packages/agents-core/`, `packages/agents-openai/`, `packages/agents-realtime/`, `packages/agents-extensions/`: Each has its own `package.json`, `src/`, `test/`, and build scripts.
-- `docs/`: Documentation source; run with `pnpm docs:dev` or build with `pnpm -F docs build`.
+- `docs/`: Documentation source; develop with `pnpm docs:dev` or build with `pnpm docs:build`.
 - `examples/`: Subdirectories (e.g. `basic`, `agent-patterns`) with their own `package.json` and start scripts.
-- `scripts/dev.ts`: Runs concurrent build-watchers and the docs dev server (`pnpm dev`).
+- `scripts/dev.mts`: Runs concurrent build-watchers and the docs dev server (`pnpm dev`).
 - `scripts/embedMeta.ts`: Generates `src/metadata.ts` for each package before build.
 - `helpers/tests/`: Shared test utilities.
 - `README.md`: High-level overview and installation instructions.
@@ -50,7 +51,7 @@ The OpenAI Agents JS repository is a pnpm-managed monorepo that provides:
 
 Before submitting changes, ensure all checks pass:
 
-### Unit Tests and Type Checking Examples
+### Unit Tests and Type Checking
 
 - Check the compilation across all packages and examples:
   ```bash
@@ -61,11 +62,19 @@ Before submitting changes, ensure all checks pass:
   CI=1 pnpm test
   ```
 - Tests are located under each package in `packages/<pkg>/test/`.
-- Using `CI=1` makes sure that the tests don't automatically run in watch mode
+- The test script already sets `CI=1` to avoid watch mode.
 
 ### Integration Tests
 
-- Do NOT try to run them. Integration tests currently require a valid OpenAI Account.
+- Not required for typical contributions. These tests rely on a local npm registry (Verdaccio) and other environment setup.
+- To run locally only if needed:
+  ```bash
+  pnpm local-npm:start   # starts Verdaccio on :4873
+  pnpm local-npm:publish # public pacakges to the local repo
+  pnpm test:integration  # runs integration tests
+  ```
+
+See [this README](integration-tests/README.md) for details.
 
 ### Code Coverage
 
@@ -106,7 +115,7 @@ Before submitting changes, ensure all checks pass:
 - Documentation site:
   ```bash
   pnpm docs:dev
-  pnpm -F docs build
+  pnpm docs:build
   ```
 - Examples:
   ```bash
@@ -132,6 +141,11 @@ Before submitting changes, ensure all checks pass:
 - Run `pnpm lint` and fix all errors locally.
 - Use `pnpm build` to catch type errors.
 
+## Prerequisites
+
+- Node.js 22+ recommended.
+- pnpm 10+ (`corepack enable` is recommended to manage versions).
+
 ## Development Workflow
 
 1.  Sync with `main` (or default branch).
@@ -160,7 +174,8 @@ Before submitting changes, ensure all checks pass:
   - `build`: changes that affect the build system
   - `ci`: CI configuration
   - `style`: code style (formatting, missing semicolons, etc.)
-  - `TYP`: type-related changes
+  - `types`: type-related changes
+  - `revert`: reverts a previous commit
 - Commit message format:
 
   ```
@@ -191,4 +206,4 @@ Before submitting changes, ensure all checks pass:
 - Study `vitest.config.ts` for test patterns (e.g., setup files, aliasing).
 - Explore `scripts/embedMeta.ts` for metadata generation logic.
 - Examples in `examples/` are fully functional apps—run them to understand usage.
-- Docs in `docs/src/` use Astro and Starlight; pages mirror package APIs under `docs/src/openai/agents`.
+- Docs in `docs/src/` use Astro and Starlight; authored content lives under `docs/src/content/docs/` and mirrors package APIs.

README.md

@@ -30,7 +30,7 @@ Explore the [`examples/`](examples/) directory to see the SDK in action.
 - [x] **Guardrails**: Input and output validation for safety and reliability.
 - [x] **Parallelization**: Run agents or tool calls in parallel and aggregate results.
 - [x] **Human-in-the-Loop**: Integrate human approval or intervention into workflows.
-- [x] **Realtime Voice Agents**: Build realtime voice agents using WebRTC or Websockets
+- [x] **Realtime Voice Agents**: Build realtime voice agents using WebRTC or WebSockets
 - [x] **Local MCP Server Support**: Give an Agent access to a locally running MCP server to provide tools
 - [x] **Separate optimized browser package**: Dedicated package meant to run in the browser for Realtime agents.
 - [x] **Broader model support**: Use non-OpenAI models through the Vercel AI SDK adapter
@@ -166,11 +166,11 @@ const agent = new RealtimeAgent({
   tools: [getWeatherTool],
 });
 
-// Intended to be run the browser
-const { apiKey } = await fetch('/path/to/ephemerial/key/generation').then(
+// Intended to run in the browser
+const { apiKey } = await fetch('/path/to/ephemeral/key/generation').then(
   (resp) => resp.json(),
 );
-// automatically configures audio input/output so start talking
+// Automatically configures audio input/output — start talking
 const session = new RealtimeSession(agent);
 await session.connect({ apiKey });
 ```
@@ -181,8 +181,8 @@ The [`examples/`](examples/) directory contains a series of examples to get star
 
 - `pnpm examples:basic` - Basic example with handoffs and tool calling
 - `pnpm examples:agents-as-tools` - Using agents as tools for translation
-- `pnpm examples:web-search` - Using the web search tool
-- `pnpm examples:file-search` - Using the file search tool
+- `pnpm examples:tools-web-search` - Using the web search tool
+- `pnpm examples:tools-file-search` - Using the file search tool
 - `pnpm examples:deterministic` - Deterministic multi-agent workflow
 - `pnpm examples:parallelization` - Running agents in parallel and picking the best result
 - `pnpm examples:human-in-the-loop` - Human approval for certain tool calls
@@ -244,10 +244,16 @@ If you want to contribute or edit the SDK/examples:
 2. Build the project
 
    ```bash
-   pnpm build
+   pnpm build && pnpm -r build-check
    ```
 
-3. Run tests, linter, etc. (add commands as appropriate for your project)
+3. Run tests and linter
+
+   ```bash
+   pnpm test && pnpm lint
+   ```
+
+See `AGENTS.md` and `CONTRIBUTING.md` for the full contributor guide.
 
 ## Acknowledgements
 

docs/README.md

@@ -23,5 +23,5 @@ pnpm docs:translate
 The docs are automatically built and deployed using GitHub Actions. To build them locally run:
 
 ```bash
-pnpm -F docs build
+pnpm docs:build
 ```

docs/src/content/docs/guides/agents.mdx

@@ -147,7 +147,7 @@ Supplying tools doesn’t guarantee the LLM will call one. You can **force** too
 
 After a tool call the SDK automatically resets `tool_choice` back to `'auto'`. This prevents
 the model from entering an infinite loop where it repeatedly tries to call the tool. You can
-override this behaviour via the `resetToolChoice` flag or by configuring
+override this behavior via the `resetToolChoice` flag or by configuring
 `toolUseBehavior`:
 
 - `'run_llm_again'` (default) – run the LLM again with the tool result.

docs/src/content/docs/guides/config.mdx

@@ -1,6 +1,6 @@
 ---
 title: Configuring the SDK
-description: Customize API keys, tracing and logging behaviour
+description: Customize API keys, tracing and logging behavior
 ---
 
 import { Code } from '@astrojs/starlight/components';

docs/src/content/docs/guides/tools.mdx

@@ -99,7 +99,7 @@ See [`filesystem-example.ts`](https://github.com/openai/openai-agents-js/tree/ma
 
 ---
 
-## Tool use behaviour
+## Tool use behavior
 
 Refer to the [Agents guide](/openai-agents-js/guides/agents#forcing-tool-use) for controlling when and how a model
 must use tools (`tool_choice`, `toolUseBehavior`, etc.).

docs/src/content/docs/guides/voice-agents/quickstart.mdx

@@ -44,7 +44,7 @@ import thinClientExample from '../../../../../../examples/docs/voice-agents/thin
 
 2. **Generate a client ephemeral token**
 
-   As this application will run in the users browser, we need a secure way to connect to the model through the Realtime API. For this we can use a [ephemeral client key](https://platform.openai.com/docs/guides/realtime#creating-an-ephemeral-token) that should get generated on your backend server. For testing purposes you can also generate a key using `curl` and your regular OpenAI API key.
+   As this application will run in the user's browser, we need a secure way to connect to the model through the Realtime API. For this we can use an [ephemeral client key](https://platform.openai.com/docs/guides/realtime#creating-an-ephemeral-token) that should be generated on your backend server. For testing purposes you can also generate a key using `curl` and your regular OpenAI API key.
 
    ```bash
    curl -X POST https://api.openai.com/v1/realtime/sessions \

docs/src/content/docs/ja/guides/config.mdx

@@ -1,6 +1,6 @@
 ---
 title: SDK の設定
-description: Customize API keys, tracing and logging behaviour
+description: Customize API keys, tracing and logging behavior
 ---
 
 import { Code } from '@astrojs/starlight/components';

examples/docs/readme/readme-voice-agent.ts

@@ -17,11 +17,11 @@ const agent = new RealtimeAgent({
 });
 
 async function main() {
-  // Intended to be run the browser
-  const { apiKey } = await fetch('/path/to/ephemerial/key/generation').then(
+  // Intended to run in the browser
+  const { apiKey } = await fetch('/path/to/ephemeral/key/generation').then(
     (resp) => resp.json(),
   );
-  // automatically configures audio input/output so start talking
+  // Automatically configures audio input/output — start talking
   const session = new RealtimeSession(agent);
   await session.connect({ apiKey });
 }