docs: improve core components documentation

src/agents/agent.py

@@ -37,6 +37,19 @@
 
 @dataclass
 class ToolsToFinalOutputResult:
+    """Result type for processing tool outputs into final agent outputs.
+
+    This class helps manage the transition between tool execution results
+    and the final output of an agent run. It determines whether more LLM
+    processing is needed or if we have reached the final output state.
+
+    Attributes:
+        is_final_output: Whether this is the final output. If False, the LLM 
+            will run again and receive the tool call output.
+        final_output: The final output value. Can be None if `is_final_output` 
+            is False, otherwise must match the `output_type` of the agent.
+    """
+
     is_final_output: bool
     """Whether this is the final output. If False, the LLM will run again and receive the tool call
     output.
@@ -73,18 +86,31 @@ class MCPConfig(TypedDict):
 
 @dataclass
 class AgentBase(Generic[TContext]):
-    """Base class for `Agent` and `RealtimeAgent`."""
+    """Base class for all agent implementations in the OpenAI Agents SDK.
+
+    This class provides the core functionality shared between standard agents
+    and realtime agents. It manages tools, model settings, and agent configuration.
+
+    Generic Args:
+        TContext: The type of context maintained during agent execution.
+
+    Key Features:
+        - Tool management and execution
+        - Model configuration
+        - Handoff support for agent collaboration
+        - Context management across runs
+    """
 
     name: str
-    """The name of the agent."""
+    """The name of the agent, used for identification and logging."""
 
     handoff_description: str | None = None
     """A description of the agent. This is used when the agent is used as a handoff, so that an
     LLM knows what it does and when to invoke it.
     """
 
     tools: list[Tool] = field(default_factory=list)
-    """A list of tools that the agent can use."""
+    """A list of tools that the agent has access to and can use during execution."""
 
     mcp_servers: list[MCPServer] = field(default_factory=list)
     """A list of [Model Context Protocol](https://modelcontextprotocol.io/) servers that

src/agents/computer.py

@@ -6,8 +6,19 @@
 
 
 class Computer(abc.ABC):
-    """A computer implemented with sync operations. The Computer interface abstracts the
-    operations needed to control a computer or browser."""
+    """Abstract interface for computer and browser control operations.
+
+    This interface defines the standard operations that can be performed on a computer
+    or browser environment, such as:
+    - Mouse movements and clicks
+    - Keyboard input
+    - Screenshot capture
+    - Window/viewport dimensions
+    - Environment detection
+
+    Implementations should provide synchronous operations for each method to ensure
+    reliable control across different platforms and environments.
+    """
 
     @property
     @abc.abstractmethod

src/agents/guardrail.py

@@ -18,7 +18,17 @@
 
 @dataclass
 class GuardrailFunctionOutput:
-    """The output of a guardrail function."""
+    """Output from a guardrail function's validation check.
+
+    This class represents the result of executing a guardrail's validation logic.
+    It includes both the validation result and optional detailed information about
+    what was checked and why the validation succeeded or failed.
+
+    Use this to:
+    - Track guardrail validation results
+    - Provide detailed feedback about validation checks
+    - Control agent execution flow based on validation
+    """
 
     output_info: Any
     """
@@ -29,6 +39,7 @@ class GuardrailFunctionOutput:
     tripwire_triggered: bool
     """
     Whether the tripwire was triggered. If triggered, the agent's execution will be halted.
+    Set to True to stop agent execution when validation fails.
     """
 
 

src/agents/mcp/__init__.py

@@ -1,3 +1,9 @@
+"""Model Context Protocol (MCP) for OpenAI Agents SDK.
+
+Provides server implementations and utilities for Model Context Protocol,
+enabling standardized communication between agents and external tools.
+"""
+
 try:
     from .server import (
         MCPServer,

src/agents/mcp/server.py

@@ -230,7 +230,17 @@ def create_streams(
             GetSessionIdCallback | None,
         ]
     ]:
-        """Create the streams for the server."""
+        """Create communication streams for the MCP server.
+
+        Returns:
+            A context manager that yields a tuple containing:
+            - A receive stream for incoming messages and exceptions
+            - A send stream for outgoing messages
+            - An optional callback for getting session IDs
+
+        This method is used internally by server implementations to establish
+        bidirectional communication channels with the MCP service.
+        """
         pass
 
     async def __aenter__(self):
@@ -245,6 +255,17 @@ def invalidate_tools_cache(self):
         self._cache_dirty = True
 
     async def _run_with_retries(self, func: Callable[[], Awaitable[T]]) -> T:
+        """Execute a function with exponential backoff retry logic.
+
+        Args:
+            func: Async function to execute with retries.
+
+        Returns:
+            The result of the function if successful.
+
+        Retries failed operations using exponential backoff based on
+        max_retry_attempts and retry_backoff_seconds_base settings.
+        """
         attempts = 0
         while True:
             try:

src/agents/memory/openai_conversations_session.py

@@ -20,12 +20,33 @@ async def start_openai_conversations_session(openai_client: AsyncOpenAI | None =
 
 
 class OpenAIConversationsSession(SessionABC):
+    """Session implementation using OpenAI's Conversations API for persistence.
+
+    This class provides conversation history storage and retrieval using OpenAI's
+    Conversations API. It automatically manages conversation IDs and handles
+    API communication for storing and retrieving conversation items.
+
+    Features:
+        - Automatic session creation and management
+        - Persistent storage via OpenAI's infrastructure
+        - Support for retrieving paginated history
+        - Automatic client configuration
+    """
+
     def __init__(
         self,
         *,
         conversation_id: str | None = None,
         openai_client: AsyncOpenAI | None = None,
     ):
+        """Initialize an OpenAI Conversations session.
+
+        Args:
+            conversation_id: Optional existing conversation ID to use.
+                If None, a new conversation will be created.
+            openai_client: Optional custom OpenAI client to use.
+                If None, uses default client or creates a new one.
+        """
         self._session_id: str | None = conversation_id
         _openai_client = openai_client
         if _openai_client is None:

src/agents/models/chatcmpl_helpers.py

@@ -10,8 +10,25 @@
 
 
 class ChatCmplHelpers:
+    """Helper utilities for OpenAI chat completions API integration.
+
+    This class provides utilities for working with OpenAI's chat completions API,
+    handling common tasks like:
+    - Determining if a client is using OpenAI's official API
+    - Managing response storage settings
+    - Configuring streaming options
+    """
+
     @classmethod
-    def is_openai(cls, client: AsyncOpenAI):
+    def is_openai(cls, client: AsyncOpenAI) -> bool:
+        """Check if the client is using the official OpenAI API.
+
+        Args:
+            client: The AsyncOpenAI client instance to check
+
+        Returns:
+            True if using api.openai.com, False otherwise
+        """
         return str(client.base_url).startswith("https://api.openai.com")
 
     @classmethod

src/agents/models/interface.py

@@ -17,24 +17,53 @@
 
 
 class ModelTracing(enum.Enum):
+    """Configuration for model execution tracing and debugging.
+
+    This enum controls how much information is collected during model execution
+    for debugging, monitoring, and analysis purposes.
+    """
+
     DISABLED = 0
-    """Tracing is disabled entirely."""
+    """Tracing is disabled entirely. No debug information is collected."""
 
     ENABLED = 1
-    """Tracing is enabled, and all data is included."""
+    """Full tracing is enabled. All data including inputs and outputs is collected."""
 
     ENABLED_WITHOUT_DATA = 2
-    """Tracing is enabled, but inputs/outputs are not included."""
+    """Tracing is enabled but sensitive data is excluded. Useful for production monitoring."""
 
     def is_disabled(self) -> bool:
+        """Check if tracing is completely disabled.
+
+        Returns:
+            True if no tracing information should be collected.
+        """
         return self == ModelTracing.DISABLED
 
     def include_data(self) -> bool:
+        """Check if full data should be included in traces.
+
+        Returns:
+            True if input/output data should be included in traces.
+        """
         return self == ModelTracing.ENABLED
 
 
 class Model(abc.ABC):
-    """The base interface for calling an LLM."""
+    """Base interface for Large Language Model interactions.
+
+    This abstract class defines the contract for all model implementations
+    in the OpenAI Agents SDK. It provides methods for both standard and
+    streaming responses from language models.
+
+    Key responsibilities:
+        - Handle model API communication
+        - Process system instructions and user inputs
+        - Apply model settings and configurations
+        - Manage tool and handoff integrations
+        - Support tracing and debugging
+        - Handle both sync and streaming responses
+    """
 
     @abc.abstractmethod
     async def get_response(

src/agents/models/multi_provider.py

@@ -8,13 +8,37 @@
 
 
 class MultiProviderMap:
-    """A map of model name prefixes to ModelProviders."""
+    """Registry for managing multiple model providers in the system.
+
+    This class maintains a mapping between model name prefixes and their
+    corresponding ModelProvider implementations. It enables:
+    - Dynamic registration of model providers
+    - Provider lookup by model prefix
+    - Support for multiple model backends
+    - Flexible provider management
+
+    Example:
+        ```python
+        map = MultiProviderMap()
+        map.add_provider("openai", OpenAIProvider())
+        map.add_provider("custom", CustomProvider())
+        provider = map.get_provider("openai")  # Get OpenAI provider
+        ```
+    """
 
     def __init__(self):
+        """Initialize an empty provider mapping."""
         self._mapping: dict[str, ModelProvider] = {}
 
     def has_prefix(self, prefix: str) -> bool:
-        """Returns True if the given prefix is in the mapping."""
+        """Check if a provider exists for the given prefix.
+
+        Args:
+            prefix: The model name prefix to check
+
+        Returns:
+            True if a provider is registered for this prefix
+        """
         return prefix in self._mapping
 
     def get_mapping(self) -> dict[str, ModelProvider]:

src/agents/realtime/agent.py

@@ -25,18 +25,29 @@
 
 @dataclass
 class RealtimeAgent(AgentBase, Generic[TContext]):
-    """A specialized agent instance that is meant to be used within a `RealtimeSession` to build
-    voice agents. Due to the nature of this agent, some configuration options are not supported
-    that are supported by regular `Agent` instances. For example:
-    - `model` choice is not supported, as all RealtimeAgents will be handled by the same model
-      within a `RealtimeSession`.
-    - `modelSettings` is not supported, as all RealtimeAgents will be handled by the same model
-      within a `RealtimeSession`.
-    - `outputType` is not supported, as RealtimeAgents do not support structured outputs.
-    - `toolUseBehavior` is not supported, as all RealtimeAgents will be handled by the same model
-      within a `RealtimeSession`.
-    - `voice` can be configured on an `Agent` level; however, it cannot be changed after the first
-      agent within a `RealtimeSession` has spoken.
+    """Specialized agent for real-time interactive scenarios like voice conversations.
+
+    RealtimeAgent is designed to operate within a RealtimeSession for building
+    interactive voice and streaming agents. It provides real-time response
+    capabilities while maintaining consistency across a session.
+
+    Key Features:
+        - Real-time streaming responses
+        - Voice interaction support
+        - Session-wide model consistency
+        - Streamlined configuration for real-time use
+
+    Limitations:
+        - Model selection is fixed per RealtimeSession
+        - Model settings are session-wide
+        - No structured output support
+        - Tool behavior is session-controlled
+        - Voice settings are immutable after first use
+
+    Note:
+        Unlike standard Agents, RealtimeAgents share core settings within
+        their session to ensure consistent behavior and performance in
+        real-time scenarios.
 
     See `AgentBase` for base parameters that are shared with `Agent`s.
     """

src/agents/realtime/events.py

@@ -15,21 +15,33 @@
 
 @dataclass
 class RealtimeEventInfo:
+    """Base information included in all realtime events.
+
+    This class provides the common context and metadata that is
+    shared across all realtime event types in the system.
+    """
+
     context: RunContextWrapper
-    """The context for the event."""
+    """The execution context for the event, containing state and settings."""
 
 
 @dataclass
 class RealtimeAgentStartEvent:
-    """A new agent has started."""
+    """Event emitted when a new realtime agent begins execution.
+
+    This event marks the beginning of an agent's lifecycle in a realtime
+    session. It provides access to the agent instance and execution context
+    for monitoring and management purposes.
+    """
 
     agent: RealtimeAgent
-    """The new agent."""
+    """The agent instance that is starting execution."""
 
     info: RealtimeEventInfo
-    """Common info for all events, such as the context."""
+    """Common event information including execution context."""
 
     type: Literal["agent_start"] = "agent_start"
+    """Discriminator field to identify this as an agent start event."""
 
 
 @dataclass