openai · rm-openai · May 18, 2025 · May 16, 2025 · May 16, 2025
diff --git a/AGENTS.md b/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.