From 14cc5fa2b37c172c110ebaa042735b4be1c365da Mon Sep 17 00:00:00 2001
From: jawwad-ali <alijawwad001@gmail.com>
Date: Thu, 4 Jun 2026 23:33:16 +0500
Subject: [PATCH] fix: export ToolContext, MCPToolChoice, and RequestUsage from
 agents

These are user-facing types that previously required submodule
imports: ToolContext is the documented context type for function
tools, MCPToolChoice is the ModelSettings.tool_choice value for
forcing a hosted MCP tool, and RequestUsage is the element type of
Usage.request_usage_entries. Re-export them from the top-level
package and add a regression test covering the public export surface.
---
 src/agents/__init__.py            |  8 ++++--
 tests/test_public_type_exports.py | 42 +++++++++++++++++++++++++++++++
 2 files changed, 48 insertions(+), 2 deletions(-)
 create mode 100644 tests/test_public_type_exports.py

diff --git a/src/agents/__init__.py b/src/agents/__init__.py
index 9cb7f05fe3..73fa097baa 100644
--- a/src/agents/__init__.py
+++ b/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",
diff --git a/tests/test_public_type_exports.py b/tests/test_public_type_exports.py
new file mode 100644
index 0000000000..ff8ac1c343
--- /dev/null
+++ b/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"