AGENTS.md

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:

   make format
   make lint
   make mypy

2. Run the tests:

   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):

   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:

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.