github-featured/openai--openai-agents-python
2
0
Fork 0
Code Issues Pull Requests Deployments Models Agent Notes Packages Projects Releases Wiki Activity

docs: improve AGENTS.md structure

Browse Source
This commit is contained in:
Kazuhiro Sera
2026-01-21 12:04:38 +09:00
parent 038c84e0bc
commit 3acfa826be
1 changed files with 58 additions and 64 deletions
Download Patch File Download Diff File Expand all files Collapse all files
AGENTS.md
+58 -64
View File
@@ -6,22 +6,15 @@ This guide helps new contributors get started with the OpenAI Agents Python repo
## Table of Contents
1. [Mandatory Skill Usage](#mandatory-skill-usage)
2. [ExecPlans](#planning-execplans)
3. [Overview](#overview)
4. [Repo Structure & Important Files](#repo-structure--important-files)
5. [Testing & Automated Checks](#testing--automated-checks)
6. [Repo-Specific Utilities](#repo-specific-utilities)
7. [Style, Linting & Type Checking](#style-linting--type-checking)
8. [Development Workflow](#development-workflow)
9. [Pull Request & Commit Guidelines](#pull-request--commit-guidelines)
10. [Review Process & What Reviewers Look For](#review-process--what-reviewers-look-for)
11. [Tips for Navigating the Repo](#tips-for-navigating-the-repo)
12. [Prerequisites](#prerequisites)
1. [Policies & Mandatory Rules](#policies--mandatory-rules)
2. [Project Structure Guide](#project-structure-guide)
3. [Operation Guide](#operation-guide)
## Mandatory Skill Usage
## Policies & Mandatory Rules
### `$code-change-verification`
### Mandatory Skill Usage
#### `$code-change-verification`
Run `$code-change-verification` before marking work complete when changes affect runtime code, tests, or build/test behavior.
@@ -33,21 +26,23 @@ Run it when you change:
You can skip `$code-change-verification` for docs-only or repo-meta changes (for example, `docs/`, `.codex/`, `README.md`, `AGENTS.md`, `.github/`), unless a user explicitly asks to run the full verification stack.
### `$openai-knowledge`
#### `$openai-knowledge`
When working on OpenAI API or OpenAI platform integrations in this repo (Responses API, tools, streaming, Realtime API, auth, models, rate limits, MCP, Agents SDK or ChatGPT Apps SDK), use `$openai-knowledge` to pull authoritative docs via the OpenAI Developer Docs MCP server (and guide setup if it is not configured).
## Planning & ExecPlans
### ExecPlans
Call out potential backward compatibility or public API risks early in your plan and confirm the approach before implementing changes that could impact users.
Use an ExecPlan when work is multi-step, spans several files, involves new features or refactors, or is likely to take more than about an hour. Start with the template and rules in `PLANS.md`, keep milestones and living sections (Progress, Surprises & Discoveries, Decision Log, Outcomes & Retrospective) up to date as you execute, and rewrite the plan if scope shifts. If you intentionally skip an ExecPlan for a complex task, note why in your response so reviewers understand the choice.
## Overview
## Project Structure Guide
### Overview
The OpenAI Agents Python repository provides the Python Agents SDK, examples, and documentation built with MkDocs. Use `uv run python ...` for Python commands to ensure a consistent environment.
## Repo Structure & Important Files
### Repo Structure & Important Files
- `src/agents/`: Core library implementation.
- `tests/`: Test suite; see `tests/README.md` for snapshot guidance.
@@ -60,13 +55,38 @@ The OpenAI Agents Python repository provides the Python Agents SDK, examples, an
- `.github/PULL_REQUEST_TEMPLATE/pull_request_template.md`: Pull request template to use when opening PRs.
- `site/`: Built documentation output.
## Testing & Automated Checks
## Operation Guide
### Prerequisites
- Python 3.9+.
- `uv` installed for dependency management (`uv sync`) and `uv run` for Python commands.
- `make` available to run repository tasks.
### Development Workflow
1. Sync with `main` and create a feature branch:
```bash
git checkout -b feat/<short-description>
```
2. If dependencies changed or you are setting up the repo, run `make sync`.
3. Implement changes and add or update tests alongside code updates.
4. Highlight backward compatibility or API risks in your plan before implementing breaking or user-facing changes.
5. Build docs when you touch documentation:
```bash
make build-docs
```
6. When `$code-change-verification` applies, run it to execute the full verification stack before marking work complete.
7. Commit with concise, imperative messages; keep commits small and focused, then open a pull request.
8. When reporting code changes as complete (after substantial code work), invoke `$pr-draft-summary` to generate the required PR summary block with change summary, PR title, and draft description.
### Testing & Automated Checks
Before submitting changes, ensure relevant checks pass and extend tests when you touch code.
When `$code-change-verification` applies, run it to execute the required verification stack from the repository root. Rerun the full stack after applying fixes.
### Unit tests and type checking
#### Unit tests and type checking
- Run the full test suite:
```bash
@@ -81,7 +101,7 @@ When `$code-change-verification` applies, run it to execute the required verific
make mypy
```
### Snapshot tests
#### Snapshot tests
Some tests rely on inline snapshots; see `tests/README.md` for details. Re-run `make tests` after updating snapshots.
@@ -94,14 +114,21 @@ Some tests rely on inline snapshots; see `tests/README.md` for details. Re-run `
make snapshots-create
```
### Coverage
#### Coverage
- Generate coverage (fails if coverage drops below threshold):
```bash
make coverage
```
### Mandatory local run order
#### Formatting, linting, and type checking
- Formatting and linting use `ruff`; run `make format` (applies fixes) and `make lint` (checks only).
- Type hints must pass `make mypy`.
- Write comments as full sentences ending with a period.
- Imports are managed by Ruff and should stay sorted.
#### Mandatory local run order
When `$code-change-verification` applies, run the full sequence in order (or use the skill scripts):
@@ -112,7 +139,7 @@ make mypy
make tests
```
## Repo-Specific Utilities
### Utilities & Tips
- Install or refresh development dependencies:
```bash
@@ -133,39 +160,20 @@ make tests
make snapshots-fix
make snapshots-create
```
- Use `examples/` to see common SDK usage patterns.
- Review `Makefile` for common commands and use `uv run` for Python invocations.
- Explore `docs/` and `docs/scripts/` to understand the documentation pipeline.
- Consult `tests/README.md` for test and snapshot workflows.
- Check `mkdocs.yml` to understand how docs are organized.
## Style, Linting & Type Checking
- Formatting and linting use `ruff`; run `make format` (applies fixes) and `make lint` (checks only).
- Type hints must pass `make mypy`.
- Write comments as full sentences ending with a period.
- Imports are managed by Ruff and should stay sorted.
## Development Workflow
1. Sync with `main` and create a feature branch:
```bash
git checkout -b feat/<short-description>
```
2. If dependencies changed or you are setting up the repo, run `make sync`.
3. Implement changes and add or update tests alongside code updates.
4. Highlight backward compatibility or API risks in your plan before implementing breaking or user-facing changes.
5. Build docs when you touch documentation:
```bash
make build-docs
```
6. When `$code-change-verification` applies, run it to execute the full verification stack before marking work complete.
7. Commit with concise, imperative messages; keep commits small and focused, then open a pull request.
8. When reporting code changes as complete (after substantial code work), invoke `$pr-draft-summary` to generate the required PR summary block with change summary, PR title, and draft description.
## Pull Request & Commit Guidelines
### Pull Request & Commit Guidelines
- Use the template at `.github/PULL_REQUEST_TEMPLATE/pull_request_template.md`; include a summary, test plan, and issue number if applicable.
- Add tests for new behavior when feasible and update documentation for user-facing changes.
- Run `make format`, `make lint`, `make mypy`, and `make tests` before marking work ready.
- Commit messages should be concise and written in the imperative mood. Small, focused commits are preferred.
## Review Process & What Reviewers Look For
### Review Process & What Reviewers Look For
- ✅ Checks pass (`make format`, `make lint`, `make mypy`, `make tests`).
- ✅ Tests cover new behavior and edge cases.
@@ -173,17 +181,3 @@ make tests
- ✅ Public APIs and user-facing behavior changes are documented.
- ✅ Examples are updated if behavior changes.
- ✅ History is clean with a clear PR description.
## Tips for Navigating the Repo
- Use `examples/` to see common SDK usage patterns.
- Review `Makefile` for common commands and use `uv run` for Python invocations.
- Explore `docs/` and `docs/scripts/` to understand the documentation pipeline.
- Consult `tests/README.md` for test and snapshot workflows.
- Check `mkdocs.yml` to understand how docs are organized.
## Prerequisites
- Python 3.9+.
- `uv` installed for dependency management (`uv sync`) and `uv run` for Python commands.
- `make` available to run repository tasks.