fix: export ToolContext, MCPToolChoice, and RequestUsage from agents

src/agents/__init__.py

@@ -81,7 +81,7 @@
     SessionSettings,
     is_openai_responses_compaction_aware_session,
 )
-from .model_settings import ModelSettings
+from .model_settings import MCPToolChoice, ModelSettings
 from .models.interface import Model, ModelProvider, ModelTracing
 from .models.multi_provider import MultiProvider
 from .models.openai_agent_registration import OpenAIAgentRegistrationConfig
@@ -187,6 +187,7 @@
     resolve_computer,
     tool_namespace,
 )
+from .tool_context import ToolContext
 from .tool_guardrails import (
     ToolGuardrailFunctionOutput,
     ToolInputGuardrail,
@@ -242,7 +243,7 @@
     transcription_span,
     turn_span,
 )
-from .usage import Usage
+from .usage import RequestUsage, Usage
 from .version import __version__
 
 if TYPE_CHECKING:
@@ -348,6 +349,7 @@ def enable_verbose_stdout_logging():
     "ModelProvider",
     "ModelTracing",
     "ModelSettings",
+    "MCPToolChoice",
     "ModelRetryAdvice",
     "ModelRetryAdviceRequest",
     "ModelRetryBackoffSettings",
@@ -436,6 +438,7 @@ def enable_verbose_stdout_logging():
     "AgentHookContext",
     "RunContextWrapper",
     "TContext",
+    "ToolContext",
     "RunErrorDetails",
     "RunErrorData",
     "RunErrorHandler",
@@ -511,6 +514,7 @@ def enable_verbose_stdout_logging():
     "tool_namespace",
     "resolve_computer",
     "dispose_resolved_computers",
+    "RequestUsage",
     "Usage",
     "add_trace_processor",
     "agent_span",

tests/test_public_type_exports.py

@@ -0,0 +1,42 @@
+"""Verify that user-facing helper types are re-exported from the top-level agents package."""
+
+import agents
+from agents import (
+    model_settings as model_settings_module,
+    tool_context as tool_context_module,
+    usage as usage_module,
+)
+
+
+def test_tool_context_is_exported_at_top_level() -> None:
+    # ToolContext is the documented context type for function tools and lifecycle hooks,
+    # so it must be importable from `agents` like RunContextWrapper.
+    from agents import ToolContext
+
+    assert ToolContext is tool_context_module.ToolContext
+    assert "ToolContext" in agents.__all__
+
+
+def test_mcp_tool_choice_is_exported_at_top_level() -> None:
+    # MCPToolChoice is the value users assign to ModelSettings.tool_choice to force a
+    # specific hosted MCP tool, so it must be importable alongside ModelSettings.
+    from agents import MCPToolChoice
+
+    assert MCPToolChoice is model_settings_module.MCPToolChoice
+    assert "MCPToolChoice" in agents.__all__
+
+
+def test_request_usage_is_exported_at_top_level() -> None:
+    # RequestUsage is the element type of Usage.request_usage_entries, so users need it
+    # importable from `agents` to annotate per-request usage data.
+    from agents import RequestUsage
+
+    assert RequestUsage is usage_module.RequestUsage
+    assert "RequestUsage" in agents.__all__
+
+
+def test_exported_names_resolve_to_attributes() -> None:
+    # Every name listed in agents.__all__ should resolve via getattr so that
+    # `from agents import <name>` works for the package's whole public surface.
+    for name in agents.__all__:
+        assert hasattr(agents, name), f"agents.{name} is in __all__ but not importable"