docs: improve core components documentation

[abdul-kabir-jawed]

Documentation Improvements for Core SDK Components

Overview

This PR enhances documentation across key components of the OpenAI Agents SDK to improve developer experience, maintainability, and code clarity.

Changes

Core Agent System

• agent.py

  • Enhanced AgentBase and Agent class documentation
  • Clarified generic type parameters and inheritance relationships
  • Added detailed descriptions for key attributes and methods
  • Improved documentation of lifecycle hooks

• computer.py

  • Added comprehensive interface documentation for computer control
  • Clarified differences between sync/async implementations
  • Documented platform-specific considerations
  • Added detailed method parameter descriptions

• guardrail.py

  • Enhanced input/output guardrail documentation
  • Added examples of validation patterns
  • Clarified guardrail execution flow
  • Improved error handling documentation

Model System

• models/interface.py

  • Enhanced base Model interface documentation
  • Clarified provider implementation requirements
  • Added tracing configuration documentation
  • Improved stream handling documentation

• models/multi_provider.py

  • Added provider registry documentation
  • Clarified provider lookup and fallback behavior
  • Improved configuration documentation

• models/chatcmpl_helpers.py

  • Added OpenAI chat completion utility documentation
  • Clarified configuration options and defaults
  • Documented streaming behavior

MCP (Model Context Protocol)

• mcp/__init__.py

  • Added module-level documentation
  • Clarified MCP's role in the SDK
  • Documented available server types

• mcp/server.py

  • Enhanced server implementation documentation
  • Clarified communication patterns
  • Added tool filtering documentation

Memory System

• memory/openai_conversations_session.py
  • Added conversation session documentation
  • Clarified persistence and retrieval patterns
  • Documented initialization options

Realtime Components

• realtime/agent.py

  • Enhanced realtime agent documentation
  • Clarified session lifecycle and limitations
  • Documented voice interaction support

• realtime/events.py and model_events.py

  • Added comprehensive event system documentation
  • Clarified event flow and relationships
  • Documented event handling patterns

Voice Components

• voice/model.py
  • Enhanced TTS model settings documentation
  • Clarified audio processing options
  • Documented voice selection and configuration

Testing

• No functional changes were made

Impact

These improvements will:

1. Reduce time-to-productivity for new developers
2. Lower barriers to contribution
3. Improve code maintainability
4. Reduce common integration errors
5. Support better IDE tooling through improved type hints and docs

[seratch]

Thanks for sending this pull request. However, I don't see the necessity to have these comments and they could increase our maintenance cost in the long run. Thus, let me close the PR this time.