Implementation:Openai Openai agents python Run Examples

Knowledge Sources	Openai_Openai_agents_python
Domains	Build_Tooling, Testing, Developer_Experience
Last Updated	2026-02-11 00:00 GMT

Overview

A test harness that discovers, filters, tags, and runs example scripts under the examples/ directory with parallel execution, auto-mode, dry-run, and logging support.

Description

The run_examples.py script is a comprehensive test harness for validating the SDK's example scripts. It recursively discovers Python files under examples/ that contain a __main__ guard, applies automatic tagging (interactive, server, audio, external) based on source code analysis and file path patterns, and then filters and executes them according to user-specified criteria.

The script uses ThreadPoolExecutor for parallel execution (configurable via --jobs), with thread-safe output buffering and per-example log files written to .tmp/examples-start-logs/. It supports an auto-mode (EXAMPLES_INTERACTIVE_MODE=auto) that enables deterministic inputs and auto-approvals for interactive examples, and automatically forces serial execution when interactive examples are detected in non-auto mode to avoid shared stdin issues. A configurable auto-skip list excludes known problematic examples (those requiring extra credentials, running as servers, or hanging in automated runs).

Key features include dry-run mode (--dry-run) for listing commands without execution, rerun file generation (--write-rerun) that writes failed example paths to .tmp/examples-rerun.txt, rerun filtering (--rerun-file) for re-executing only previously failed examples, and a --collect mode that parses a previous main log to extract failure entries. The script produces a structured summary table at the end showing pass/skip/fail status for each example.

Usage

Use this script to validate that example scripts in the repository execute successfully. It is particularly useful in CI environments where the auto-mode ensures non-interactive execution. Developers can use the filter and tag-inclusion flags to selectively run subsets of examples during development.

Code Reference

Source Location

• Repository: Openai_Openai_agents_python
• File: examples/run_examples.py
• Lines: 1-569

Signature

@dataclass
class ExampleScript:
    path: Path
    tags: set[str] = field(default_factory=set)
    relpath: str  # property
    module: str   # property
    command: list[str]  # property

@dataclass
class ExampleResult:
    script: ExampleScript
    status: str
    reason: str = ""
    log_path: Path | None = None
    exit_code: int | None = None

def discover_examples(filters: Iterable[str]) -> list[ExampleScript]: ...
def detect_tags(path: Path, source: str) -> set[str]: ...
def run_examples(examples: Sequence[ExampleScript], args: argparse.Namespace) -> int: ...
def main() -> int: ...

Import

# CLI invocation (not imported as a library)
# python examples/run_examples.py

I/O Contract

Inputs

Name	Type	Required	Description
--filter, -f	str (repeatable)	No	Case-insensitive substring filter applied to relative paths
--dry-run	flag	No	List commands without running them
--include-interactive	flag	No	Include examples that prompt for user input
--include-server	flag	No	Include long-running server-style examples
--include-audio	flag	No	Include voice or realtime audio examples
--include-external	flag	No	Include examples requiring extra services (Redis, Dapr, Twilio, etc.)
--jobs, -j	int	No	Number of parallel workers (default: 4)
--auto-mode	flag	No	Force EXAMPLES_INTERACTIVE_MODE=auto
--rerun-file	str	No	Only run examples listed in this file (one path per line)
--write-rerun	flag	No	Write failures to .tmp/examples-rerun.txt
--collect	str	No	Parse a previous main log to emit a rerun list
--verbose	flag	No	Show detected tags for each example

Outputs

Name	Type	Description
Per-example log files	Text files	Written to .tmp/examples-start-logs/{example_path}.log
Main summary log	Text file	Written to .tmp/examples-start-logs/main_{timestamp}.log
Rerun list	Text file	Written to .tmp/examples-rerun.txt when --write-rerun is set
Exit code	int	0 if all examples passed, 1 if any failed
Summary table	stdout	Tabular output showing status, example path, info, and log path for each example

Usage Examples

Run All Examples with Auto Mode

python examples/run_examples.py --auto-mode

Dry Run with Filter

python examples/run_examples.py --dry-run --filter basic

Run with Parallel Jobs and Rerun Tracking

python examples/run_examples.py --jobs 8 --write-rerun --auto-mode

Rerun Only Failed Examples

python examples/run_examples.py --rerun-file .tmp/examples-rerun.txt --auto-mode

Related Pages

• Principle:Openai_Openai_agents_python_Documentation_Build_Pipeline