feat(payments): provide_http_request opt-out flag for AgentCorePaymentsPlugin

Strands' tool registry raises ValueError on duplicate tool names, so a
caller who wants to ship their own http_request currently can't — the
plugin's auto-discovered http_request crashes Agent construction first.

Add provide_http_request: bool = True to AgentCorePaymentsPluginConfig.
When True (default), behavior is unchanged: the plugin's http_request
@tool is auto-registered. When False, the plugin filters its own
http_request out of self._tools right after super().__init__() so the
caller can pass their own without a name collision.

Auto-payment of 402 responses still works against any tool whose output
emits the PAYMENT_REQUIRED: content marker — the after_tool_call hook
is independent of the tool registration, so disabling the flag does
not disable interception.

Adds 5 tests:
- default registers http_request
- opt-out drops only http_request (other plugin tools intact)
- opt-out preserves the after_tool_call/before_tool_call hooks
- config validator rejects non-bool values for the flag
- init_agent still works with the flag off

All 495 payments tests pass.

Author: aidandaly24

src/bedrock_agentcore/payments/integrations/config.py

@@ -39,6 +39,14 @@ class AgentCorePaymentsPluginConfig:
             eligible (preserving existing behavior). When set, only tool calls whose
             name appears in this list will trigger payment processing; all others are
             skipped.
+        provide_http_request: Whether the plugin should register its built-in
+            ``http_request`` ``@tool`` on the agent. Defaults to True so adding the
+            plugin gives a turnkey paid-HTTP experience. Set to False if you want
+            to ship your own ``http_request`` tool — Strands raises a ValueError
+            on duplicate tool names, so you must opt out of the plugin's version
+            before passing your own. Auto-payment of 402 responses still works
+            against any tool whose output carries the ``PAYMENT_REQUIRED:``
+            content marker, so disabling this flag does not disable interception.
     """
 
     payment_manager_arn: str
@@ -54,6 +62,7 @@ class AgentCorePaymentsPluginConfig:
     bearer_token: Optional[str] = None
     token_provider: Optional[Callable[[], str]] = None
     payment_tool_allowlist: Optional[List[str]] = None
+    provide_http_request: bool = True
 
     def __post_init__(self) -> None:
         """Validate configuration after initialization."""
@@ -87,6 +96,9 @@ def __post_init__(self) -> None:
             if not all(isinstance(t, str) for t in self.payment_tool_allowlist):
                 raise ValueError("All entries in payment_tool_allowlist must be strings")
 
+        if not isinstance(self.provide_http_request, bool):
+            raise ValueError(f"provide_http_request must be a boolean, got {type(self.provide_http_request).__name__}")
+
     def update_payment_session_id(self, payment_session_id: str) -> None:
         """Update the payment session ID.
 

src/bedrock_agentcore/payments/integrations/strands/plugin.py

@@ -58,6 +58,18 @@ def __init__(self, config: AgentCorePaymentsPluginConfig):
         super().__init__()
         self.config = config
         self.payment_manager: Optional[PaymentManager] = None
+
+        # Honor the provide_http_request opt-out: Strands' Plugin base auto-discovers
+        # every @tool method into self._tools at super().__init__(). If the caller
+        # wants to ship their own http_request, drop ours so Strands' tool registry
+        # doesn't raise ValueError on duplicate tool name.
+        if not self.config.provide_http_request:
+            self._tools = [t for t in self._tools if t.tool_name != "http_request"]
+            logger.info(
+                "provide_http_request=False — plugin's http_request tool will not be registered. "
+                "Auto-payment still triggers on any tool emitting a PAYMENT_REQUIRED: marker."
+            )
+
         logger.info("Initialized AgentCorePaymentsPlugin")
 
     def init_agent(self, agent) -> None:

tests/bedrock_agentcore/payments/integrations/strands/test_tools.py

@@ -1917,3 +1917,93 @@ def test_default_headers_dict_when_caller_omits(self, mock_client_cls):
         sent = mock_client.request.call_args.kwargs["headers"]
         assert isinstance(sent, dict)
         assert sent == {}
+
+
+class TestProvideHttpRequestOptOut:
+    """Tests for the provide_http_request config flag.
+
+    When True (default), AgentCorePaymentsPlugin registers its built-in
+    http_request @tool. When False, the tool is dropped from the plugin's
+    discovered tools so callers can ship their own http_request without
+    Strands raising ValueError on duplicate tool names.
+    """
+
+    @staticmethod
+    def _make_config(**overrides):
+        from bedrock_agentcore.payments.integrations.config import AgentCorePaymentsPluginConfig
+
+        kwargs = dict(
+            payment_manager_arn="arn:aws:payment:us-east-1:123456789012:payment-manager/test",
+            user_id="test-user",
+            payment_instrument_id="test-instrument",
+            payment_session_id="test-session",
+        )
+        kwargs.update(overrides)
+        return AgentCorePaymentsPluginConfig(**kwargs)
+
+    def test_default_provides_http_request(self):
+        """By default the plugin registers http_request alongside its other tools."""
+        from bedrock_agentcore.payments.integrations.strands.plugin import AgentCorePaymentsPlugin
+
+        plugin = AgentCorePaymentsPlugin(self._make_config())
+        tool_names = {t.tool_name for t in plugin.tools}
+        assert "http_request" in tool_names
+        # Sanity: the rest of the plugin's tools are still there.
+        assert "get_payment_instrument" in tool_names
+        assert "get_payment_session" in tool_names
+
+    def test_opt_out_drops_only_http_request(self):
+        """provide_http_request=False removes ONLY http_request from the registered tools."""
+        from bedrock_agentcore.payments.integrations.strands.plugin import AgentCorePaymentsPlugin
+
+        plugin = AgentCorePaymentsPlugin(self._make_config(provide_http_request=False))
+        tool_names = {t.tool_name for t in plugin.tools}
+        assert "http_request" not in tool_names
+        # Other plugin tools must still be present so payment-info queries still work.
+        assert "get_payment_instrument" in tool_names
+        assert "list_payment_instruments" in tool_names
+        assert "get_payment_instrument_balance" in tool_names
+        assert "get_payment_session" in tool_names
+
+    def test_opt_out_does_not_disable_payment_hook(self):
+        """Disabling the tool must not disable the after_tool_call interceptor.
+
+        A caller's own http_request that emits PAYMENT_REQUIRED-marked content
+        should still trigger the plugin's auto-pay path.
+        """
+        from bedrock_agentcore.payments.integrations.strands.plugin import AgentCorePaymentsPlugin
+
+        plugin = AgentCorePaymentsPlugin(self._make_config(provide_http_request=False))
+        hook_names = [getattr(h, "__name__", repr(h)) for h in plugin.hooks]
+        assert "after_tool_call" in hook_names
+        assert "before_tool_call" in hook_names
+
+    def test_provide_http_request_validation_rejects_non_bool(self):
+        """Config validator rejects non-boolean values for the new flag."""
+        import pytest
+
+        from bedrock_agentcore.payments.integrations.config import AgentCorePaymentsPluginConfig
+
+        with pytest.raises(ValueError, match="provide_http_request must be a boolean"):
+            AgentCorePaymentsPluginConfig(
+                payment_manager_arn="arn:aws:payment:us-east-1:123456789012:payment-manager/test",
+                user_id="test-user",
+                provide_http_request="yes",  # type: ignore[arg-type]
+            )
+
+    def test_opt_out_preserves_payment_manager_init(self):
+        """The init flow (PaymentManager initialization) is unaffected by the flag."""
+        from unittest.mock import MagicMock
+
+        from bedrock_agentcore.payments.integrations.strands.plugin import AgentCorePaymentsPlugin
+
+        plugin = AgentCorePaymentsPlugin(self._make_config(provide_http_request=False))
+        # init_agent should be callable and should not blow up just because we opted out.
+        try:
+            plugin.init_agent(agent=MagicMock())
+        except RuntimeError:
+            # Real PaymentManager call against a fake ARN — tolerate the network/IAM
+            # failure; what we care about is that init_agent doesn't trip on the flag.
+            pass
+        # Plugin object itself must still be usable
+        assert plugin.config.provide_http_request is False