langchain-agent-commerce 0.1.0__tar.gz

langchain_agent_commerce-0.1.0/.gitignore

@@ -0,0 +1,15 @@
+node_modules/
+dist/
+.venv/
+__pycache__/
+.pytest_cache/
+.ruff_cache/
+.benchmarks/
+.coverage
+coverage/
+.playwright-mcp/
+*.egg-info/
+.env
+.env.*
+.claude/settings.local.json
+.internal-docs

langchain_agent_commerce-0.1.0/LICENSE

@@ -0,0 +1,202 @@
+
+                                 Apache License
+                           Version 2.0, January 2004
+                        http://www.apache.org/licenses/
+
+   TERMS AND CONDITIONS FOR USE, REPRODUCTION, AND DISTRIBUTION
+
+   1. Definitions.
+
+      "License" shall mean the terms and conditions for use, reproduction,
+      and distribution as defined by Sections 1 through 9 of this document.
+
+      "Licensor" shall mean the copyright owner or entity authorized by
+      the copyright owner that is granting the License.
+
+      "Legal Entity" shall mean the union of the acting entity and all
+      other entities that control, are controlled by, or are under common
+      control with that entity. For the purposes of this definition,
+      "control" means (i) the power, direct or indirect, to cause the
+      direction or management of such entity, whether by contract or
+      otherwise, or (ii) ownership of fifty percent (50%) or more of the
+      outstanding shares, or (iii) beneficial ownership of such entity.
+
+      "You" (or "Your") shall mean an individual or Legal Entity
+      exercising permissions granted by this License.
+
+      "Source" form shall mean the preferred form for making modifications,
+      including but not limited to software source code, documentation
+      source, and configuration files.
+
+      "Object" form shall mean any form resulting from mechanical
+      transformation or translation of a Source form, including but
+      not limited to compiled object code, generated documentation,
+      and conversions to other media types.
+
+      "Work" shall mean the work of authorship, whether in Source or
+      Object form, made available under the License, as indicated by a
+      copyright notice that is included in or attached to the work
+      (an example is provided in the Appendix below).
+
+      "Derivative Works" shall mean any work, whether in Source or Object
+      form, that is based on (or derived from) the Work and for which the
+      editorial revisions, annotations, elaborations, or other modifications
+      represent, as a whole, an original work of authorship. For the purposes
+      of this License, Derivative Works shall not include works that remain
+      separable from, or merely link (or bind by name) to the interfaces of,
+      the Work and Derivative Works thereof.
+
+      "Contribution" shall mean any work of authorship, including
+      the original version of the Work and any modifications or additions
+      to that Work or Derivative Works thereof, that is intentionally
+      submitted to Licensor for inclusion in the Work by the copyright owner
+      or by an individual or Legal Entity authorized to submit on behalf of
+      the copyright owner. For the purposes of this definition, "submitted"
+      means any form of electronic, verbal, or written communication sent
+      to the Licensor or its representatives, including but not limited to
+      communication on electronic mailing lists, source code control systems,
+      and issue tracking systems that are managed by, or on behalf of, the
+      Licensor for the purpose of discussing and improving the Work, but
+      excluding communication that is conspicuously marked or otherwise
+      designated in writing by the copyright owner as "Not a Contribution."
+
+      "Contributor" shall mean Licensor and any individual or Legal Entity
+      on behalf of whom a Contribution has been received by Licensor and
+      subsequently incorporated within the Work.
+
+   2. Grant of Copyright License. Subject to the terms and conditions of
+      this License, each Contributor hereby grants to You a perpetual,
+      worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+      copyright license to reproduce, prepare Derivative Works of,
+      publicly display, publicly perform, sublicense, and distribute the
+      Work and such Derivative Works in Source or Object form.
+
+   3. Grant of Patent License. Subject to the terms and conditions of
+      this License, each Contributor hereby grants to You a perpetual,
+      worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+      (except as stated in this section) patent license to make, have made,
+      use, offer to sell, sell, import, and otherwise transfer the Work,
+      where such license applies only to those patent claims licensable
+      by such Contributor that are necessarily infringed by their
+      Contribution(s) alone or by combination of their Contribution(s)
+      with the Work to which such Contribution(s) was submitted. If You
+      institute patent litigation against any entity (including a
+      cross-claim or counterclaim in a lawsuit) alleging that the Work
+      or a Contribution incorporated within the Work constitutes direct
+      or contributory patent infringement, then any patent licenses
+      granted to You under this License for that Work shall terminate
+      as of the date such litigation is filed.
+
+   4. Redistribution. You may reproduce and distribute copies of the
+      Work or Derivative Works thereof in any medium, with or without
+      modifications, and in Source or Object form, provided that You
+      meet the following conditions:
+
+      (a) You must give any other recipients of the Work or
+          Derivative Works a copy of this License; and
+
+      (b) You must cause any modified files to carry prominent notices
+          stating that You changed the files; and
+
+      (c) You must retain, in the Source form of any Derivative Works
+          that You distribute, all copyright, patent, trademark, and
+          attribution notices from the Source form of the Work,
+          excluding those notices that do not pertain to any part of
+          the Derivative Works; and
+
+      (d) If the Work includes a "NOTICE" text file as part of its
+          distribution, then any Derivative Works that You distribute must
+          include a readable copy of the attribution notices contained
+          within such NOTICE file, excluding those notices that do not
+          pertain to any part of the Derivative Works, in at least one
+          of the following places: within a NOTICE text file distributed
+          as part of the Derivative Works; within the Source form or
+          documentation, if provided along with the Derivative Works; or,
+          within a display generated by the Derivative Works, if and
+          wherever such third-party notices normally appear. The contents
+          of the NOTICE file are for informational purposes only and
+          do not modify the License. You may add Your own attribution
+          notices within Derivative Works that You distribute, alongside
+          or as an addendum to the NOTICE text from the Work, provided
+          that such additional attribution notices cannot be construed
+          as modifying the License.
+
+      You may add Your own copyright statement to Your modifications and
+      may provide additional or different license terms and conditions
+      for use, reproduction, or distribution of Your modifications, or
+      for any such Derivative Works as a whole, provided Your use,
+      reproduction, and distribution of the Work otherwise complies with
+      the conditions stated in this License.
+
+   5. Submission of Contributions. Unless You explicitly state otherwise,
+      any Contribution intentionally submitted for inclusion in the Work
+      by You to the Licensor shall be under the terms and conditions of
+      this License, without any additional terms or conditions.
+      Notwithstanding the above, nothing herein shall supersede or modify
+      the terms of any separate license agreement you may have executed
+      with Licensor regarding such Contributions.
+
+   6. Trademarks. This License does not grant permission to use the trade
+      names, trademarks, service marks, or product names of the Licensor,
+      except as required for reasonable and customary use in describing the
+      origin of the Work and reproducing the content of the NOTICE file.
+
+   7. Disclaimer of Warranty. Unless required by applicable law or
+      agreed to in writing, Licensor provides the Work (and each
+      Contributor provides its Contributions) on an "AS IS" BASIS,
+      WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or
+      implied, including, without limitation, any warranties or conditions
+      of TITLE, NON-INFRINGEMENT, MERCHANTABILITY, or FITNESS FOR A
+      PARTICULAR PURPOSE. You are solely responsible for determining the
+      appropriateness of using or redistributing the Work and assume any
+      risks associated with Your exercise of permissions under this License.
+
+   8. Limitation of Liability. In no event and under no legal theory,
+      whether in tort (including negligence), contract, or otherwise,
+      unless required by applicable law (such as deliberate and grossly
+      negligent acts) or agreed to in writing, shall any Contributor be
+      liable to You for damages, including any direct, indirect, special,
+      incidental, or consequential damages of any character arising as a
+      result of this License or out of the use or inability to use the
+      Work (including but not limited to damages for loss of goodwill,
+      work stoppage, computer failure or malfunction, or any and all
+      other commercial damages or losses), even if such Contributor
+      has been advised of the possibility of such damages.
+
+   9. Accepting Warranty or Additional Liability. While redistributing
+      the Work or Derivative Works thereof, You may choose to offer,
+      and charge a fee for, acceptance of support, warranty, indemnity,
+      or other liability obligations and/or rights consistent with this
+      License. However, in accepting such obligations, You may act only
+      on Your own behalf and on Your sole responsibility, not on behalf
+      of any other Contributor, and only if You agree to indemnify,
+      defend, and hold each Contributor harmless for any liability
+      incurred by, or claims asserted against, such Contributor by reason
+      of your accepting any such warranty or additional liability.
+
+   END OF TERMS AND CONDITIONS
+
+   APPENDIX: How to apply the Apache License to your work.
+
+      To apply the Apache License to your work, attach the following
+      boilerplate notice, with the fields enclosed by brackets "[]"
+      replaced with your own identifying information. (Don't include
+      the brackets!)  The text should be enclosed in the appropriate
+      comment syntax for the file format. We also recommend that a
+      file or class name and description of purpose be included on the
+      same "printed page" as the copyright notice for easier
+      identification within third-party archives.
+
+   Copyright [yyyy] [name of copyright owner]
+
+   Licensed under the Apache License, Version 2.0 (the "License");
+   you may not use this file except in compliance with the License.
+   You may obtain a copy of the License at
+
+       http://www.apache.org/licenses/LICENSE-2.0
+
+   Unless required by applicable law or agreed to in writing, software
+   distributed under the License is distributed on an "AS IS" BASIS,
+   WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+   See the License for the specific language governing permissions and
+   limitations under the License.

langchain_agent_commerce-0.1.0/PKG-INFO

@@ -0,0 +1,123 @@
+Metadata-Version: 2.5
+Name: langchain-agent-commerce
+Version: 0.1.0
+Summary: Tools that let agents call and pay for API endpoints behind a self-hosted Agent Commerce Gateway with x402, within set spending limits.
+Project-URL: Homepage, https://acg.devlab.group
+Project-URL: Documentation, https://acg.devlab.group/docs/integrations/langchain
+Project-URL: Repository, https://github.com/devlab-group/agent-commerce-clients
+Project-URL: Issues, https://github.com/devlab-group/agent-commerce-clients/issues
+License-Expression: Apache-2.0
+License-File: LICENSE
+Keywords: agents,api,langchain,payments,x402
+Requires-Python: >=3.11
+Requires-Dist: agent-commerce-client<0.2,>=0.1.0
+Requires-Dist: langchain-core<2,>=1.8.0
+Requires-Dist: langchain<2,>=1.5.0
+Description-Content-Type: text/markdown
+
+# langchain-agent-commerce
+
+Framework tools for discovering and paying for API endpoints behind a self-hosted
+[Agent Commerce Gateway](https://acg.devlab.group), using x402 within spending limits you set.
+
+`AgentCommerceToolkit` turns the resources of a gateway into LangChain tools.
+[`agent-commerce-client`](../agent-commerce-client) handles payments, limits and filtering; this package maps its
+resource descriptions to `StructuredTool`s and builds the human-approval middleware. The behavior contract is in
+[docs/buyer-core.md](https://github.com/devlab-group/agent-commerce-clients/blob/main/docs/buyer-core.md).
+
+Documentation: <https://acg.devlab.group/docs/integrations/langchain>.
+
+## Install
+
+```bash
+pip install langchain-agent-commerce
+```
+
+Requires Python 3.11 or later and LangChain 1.x.
+
+## Quick start
+
+```python
+import os
+
+from eth_account import Account
+from langchain.agents import create_agent
+from langchain_agent_commerce import AgentCommerceToolkit
+
+toolkit = AgentCommerceToolkit(
+    gateway_url="https://merchant.example.com",
+    signer=Account.from_key(os.environ["BUYER_PRIVATE_KEY"]),
+    networks=["eip155:84532"],
+    max_per_call="0.05",
+    max_per_day="1.00",
+)
+agent = create_agent(model="openai:gpt-5-mini", tools=toolkit.get_tools())
+```
+
+Choose a chat model with LangChain tool-calling support. This example runs paid tools without human approval; see
+[Human approval](#human-approval). The toolkit accepts the keyword arguments of `AgentCommerceClient`, including
+`gateway_url`, `signer`, `networks`, `max_per_call`, `max_per_day`, `resources`, `allow_mainnet`, `approval` and
+`spend_store`. See the [core README](../agent-commerce-client/README.md) for configuration details.
+
+Each tool is a `StructuredTool` named after the resource id. Its description comes from the gateway and ends with the
+price (`Costs 0.01 USDC per call.`, `Free.` or `Paid.`), and its argument schema is the resource's JSON Schema. A tool
+returns `{"status": ..., "body": ..., "payment": ...}`, where `payment` is the decoded `PAYMENT-RESPONSE` (network,
+transaction hash, payer) or `None` for a free call.
+
+## Human approval
+
+Add the approval middleware to require a human decision before a paid call. Without it, the agent calls paid tools on
+its own within `max_per_call` and `max_per_day`, as in the quick start.
+
+By default, tools for paid resources need approval (`approval="paid"`; `"always"` and `"never"` change that).
+`toolkit.approval_middleware()` builds LangChain's `HumanInTheLoopMiddleware` (`langchain.agents.middleware`) with
+`interrupt_on` set for exactly those tools. The reviewer sees the price in the request description and can approve, edit
+or reject the call. The middleware needs a checkpointer and a `thread_id`:
+
+```python
+from langgraph.checkpoint.memory import InMemorySaver
+from langgraph.types import Command
+
+tools = toolkit.get_tools()
+agent = create_agent(
+    model="openai:gpt-5-mini",
+    tools=tools,
+    middleware=[toolkit.approval_middleware()],
+    checkpointer=InMemorySaver(),
+)
+config = {"configurable": {"thread_id": "1"}}
+result = agent.invoke({"messages": [("user", "Buy the market report")]}, config=config, version="v2")
+# result.interrupts[0].value["action_requests"] lists the paid calls awaiting a decision;
+# no invocation has been sent to the gateway yet
+result = agent.invoke(Command(resume={"decisions": [{"type": "approve"}]}), config=config, version="v2")
+```
+
+A rejection looks like `{"type": "reject", "message": "too expensive"}`; the model then receives the reason as the tool
+result. `approval_middleware()` uses the tools of the last `get_tools()` call.
+
+## Errors
+
+An `AgentCommerceError` reaches the model as tool output text, for example
+`LIMIT_EXCEEDED: Price 0.01 USDC exceeds the per-call limit of 0.005 USDC`, and the tool message gets the error status.
+It does not crash the agent. Codes: `LIMIT_EXCEEDED`, `NETWORK_NOT_ALLOWED`, `PAYMENT_FAILED`, `BACKEND_ERROR`,
+`GATEWAY_UNREACHABLE`. Configuration errors raise `ValueError` or `TypeError` when the toolkit is created.
+
+## Tests
+
+```bash
+uv run pytest langchain-agent-commerce   # from the python/ directory of the repository
+```
+
+The suite checks the tool mapping, the approval middleware, an agent run with a scripted model, and the standard
+`langchain-tests` `ToolsUnitTests` suite.
+
+The end-to-end test makes a real payment through a running gateway and chain, without a language model. Enable it with
+`ACG_E2E=1`; configuration and environment variables are listed in [`../e2e/acg_e2e.py`](../e2e/acg_e2e.py):
+
+```bash
+ACG_E2E=1 uv run pytest langchain-agent-commerce/tests/test_e2e_langchain.py -s
+```
+
+## License
+
+Apache-2.0

langchain_agent_commerce-0.1.0/README.md

@@ -0,0 +1,106 @@
+# langchain-agent-commerce
+
+Framework tools for discovering and paying for API endpoints behind a self-hosted
+[Agent Commerce Gateway](https://acg.devlab.group), using x402 within spending limits you set.
+
+`AgentCommerceToolkit` turns the resources of a gateway into LangChain tools.
+[`agent-commerce-client`](../agent-commerce-client) handles payments, limits and filtering; this package maps its
+resource descriptions to `StructuredTool`s and builds the human-approval middleware. The behavior contract is in
+[docs/buyer-core.md](https://github.com/devlab-group/agent-commerce-clients/blob/main/docs/buyer-core.md).
+
+Documentation: <https://acg.devlab.group/docs/integrations/langchain>.
+
+## Install
+
+```bash
+pip install langchain-agent-commerce
+```
+
+Requires Python 3.11 or later and LangChain 1.x.
+
+## Quick start
+
+```python
+import os
+
+from eth_account import Account
+from langchain.agents import create_agent
+from langchain_agent_commerce import AgentCommerceToolkit
+
+toolkit = AgentCommerceToolkit(
+    gateway_url="https://merchant.example.com",
+    signer=Account.from_key(os.environ["BUYER_PRIVATE_KEY"]),
+    networks=["eip155:84532"],
+    max_per_call="0.05",
+    max_per_day="1.00",
+)
+agent = create_agent(model="openai:gpt-5-mini", tools=toolkit.get_tools())
+```
+
+Choose a chat model with LangChain tool-calling support. This example runs paid tools without human approval; see
+[Human approval](#human-approval). The toolkit accepts the keyword arguments of `AgentCommerceClient`, including
+`gateway_url`, `signer`, `networks`, `max_per_call`, `max_per_day`, `resources`, `allow_mainnet`, `approval` and
+`spend_store`. See the [core README](../agent-commerce-client/README.md) for configuration details.
+
+Each tool is a `StructuredTool` named after the resource id. Its description comes from the gateway and ends with the
+price (`Costs 0.01 USDC per call.`, `Free.` or `Paid.`), and its argument schema is the resource's JSON Schema. A tool
+returns `{"status": ..., "body": ..., "payment": ...}`, where `payment` is the decoded `PAYMENT-RESPONSE` (network,
+transaction hash, payer) or `None` for a free call.
+
+## Human approval
+
+Add the approval middleware to require a human decision before a paid call. Without it, the agent calls paid tools on
+its own within `max_per_call` and `max_per_day`, as in the quick start.
+
+By default, tools for paid resources need approval (`approval="paid"`; `"always"` and `"never"` change that).
+`toolkit.approval_middleware()` builds LangChain's `HumanInTheLoopMiddleware` (`langchain.agents.middleware`) with
+`interrupt_on` set for exactly those tools. The reviewer sees the price in the request description and can approve, edit
+or reject the call. The middleware needs a checkpointer and a `thread_id`:
+
+```python
+from langgraph.checkpoint.memory import InMemorySaver
+from langgraph.types import Command
+
+tools = toolkit.get_tools()
+agent = create_agent(
+    model="openai:gpt-5-mini",
+    tools=tools,
+    middleware=[toolkit.approval_middleware()],
+    checkpointer=InMemorySaver(),
+)
+config = {"configurable": {"thread_id": "1"}}
+result = agent.invoke({"messages": [("user", "Buy the market report")]}, config=config, version="v2")
+# result.interrupts[0].value["action_requests"] lists the paid calls awaiting a decision;
+# no invocation has been sent to the gateway yet
+result = agent.invoke(Command(resume={"decisions": [{"type": "approve"}]}), config=config, version="v2")
+```
+
+A rejection looks like `{"type": "reject", "message": "too expensive"}`; the model then receives the reason as the tool
+result. `approval_middleware()` uses the tools of the last `get_tools()` call.
+
+## Errors
+
+An `AgentCommerceError` reaches the model as tool output text, for example
+`LIMIT_EXCEEDED: Price 0.01 USDC exceeds the per-call limit of 0.005 USDC`, and the tool message gets the error status.
+It does not crash the agent. Codes: `LIMIT_EXCEEDED`, `NETWORK_NOT_ALLOWED`, `PAYMENT_FAILED`, `BACKEND_ERROR`,
+`GATEWAY_UNREACHABLE`. Configuration errors raise `ValueError` or `TypeError` when the toolkit is created.
+
+## Tests
+
+```bash
+uv run pytest langchain-agent-commerce   # from the python/ directory of the repository
+```
+
+The suite checks the tool mapping, the approval middleware, an agent run with a scripted model, and the standard
+`langchain-tests` `ToolsUnitTests` suite.
+
+The end-to-end test makes a real payment through a running gateway and chain, without a language model. Enable it with
+`ACG_E2E=1`; configuration and environment variables are listed in [`../e2e/acg_e2e.py`](../e2e/acg_e2e.py):
+
+```bash
+ACG_E2E=1 uv run pytest langchain-agent-commerce/tests/test_e2e_langchain.py -s
+```
+
+## License
+
+Apache-2.0

langchain_agent_commerce-0.1.0/pyproject.toml

@@ -0,0 +1,26 @@
+[build-system]
+requires = ["hatchling"]
+build-backend = "hatchling.build"
+
+[project]
+name = "langchain-agent-commerce"
+version = "0.1.0"
+description = "Tools that let agents call and pay for API endpoints behind a self-hosted Agent Commerce Gateway with x402, within set spending limits."
+readme = "README.md"
+license = "Apache-2.0"
+requires-python = ">=3.11"
+keywords = ["langchain", "x402", "agents", "payments", "api"]
+dependencies = [
+    "agent-commerce-client>=0.1.0,<0.2",
+    "langchain>=1.5.0,<2",
+    "langchain-core>=1.8.0,<2",
+]
+
+[project.urls]
+Homepage = "https://acg.devlab.group"
+Documentation = "https://acg.devlab.group/docs/integrations/langchain"
+Repository = "https://github.com/devlab-group/agent-commerce-clients"
+Issues = "https://github.com/devlab-group/agent-commerce-clients/issues"
+
+[tool.hatch.build.targets.wheel]
+packages = ["src/langchain_agent_commerce"]

langchain_agent_commerce-0.1.0/src/langchain_agent_commerce/__init__.py

@@ -0,0 +1,5 @@
+"""LangChain integration for Agent Commerce Gateway."""
+
+from .toolkit import AgentCommerceToolkit
+
+__all__ = ["AgentCommerceToolkit"]

langchain_agent_commerce-0.1.0/src/langchain_agent_commerce/toolkit.py

@@ -0,0 +1,77 @@
+"""Map Agent Commerce Gateway resources to LangChain tools"""
+
+from __future__ import annotations
+
+from dataclasses import asdict
+from typing import Any
+
+from agent_commerce_client import AgentCommerceClient, AgentCommerceError, ResourceTool
+from langchain.agents.middleware import HumanInTheLoopMiddleware
+from langchain_core.tools import BaseTool, BaseToolkit, StructuredTool, ToolException
+from pydantic import ConfigDict, PrivateAttr
+
+
+class AgentCommerceToolkit(BaseToolkit):
+    """LangChain tools for ACG resources, paid with x402 within spending limits.
+
+    Accepts the keyword arguments of `agent_commerce_client.AgentCommerceClient`,
+    which handles payments, limits and filtering. This toolkit maps its resource
+    descriptions to `StructuredTool`s and returns client errors as tool output text.
+    """
+
+    model_config = ConfigDict(arbitrary_types_allowed=True)
+
+    client: AgentCommerceClient
+    _gated: dict[str, str] | None = PrivateAttr(default=None)
+
+    def __init__(self, **kwargs: Any) -> None:
+        super().__init__(client=AgentCommerceClient(**kwargs))
+
+    def get_tools(self) -> list[BaseTool]:
+        tools = self.client.list_tools()
+        self._gated = {tool.name: tool.description for tool in tools if tool.needs_approval}
+        return [self._tool(tool) for tool in tools]
+
+    def approval_middleware(self) -> HumanInTheLoopMiddleware:
+        """Build approval middleware for `create_agent`.
+
+        Uses the most recent `get_tools()` result, or discovers tools if needed.
+        The agent needs a checkpointer to pause and resume calls.
+        """
+        if self._gated is None:
+            self.get_tools()
+        # Include the tool description so the reviewer can see its price information
+        return HumanInTheLoopMiddleware(
+            interrupt_on={
+                name: {
+                    "allowed_decisions": ["approve", "edit", "reject"],
+                    "description": f"Tool call needs approval: {description}",
+                }
+                for name, description in (self._gated or {}).items()
+            }
+        )
+
+    def _tool(self, tool: ResourceTool) -> StructuredTool:
+        client = self.client
+
+        def run(**arguments: Any) -> dict[str, Any]:
+            try:
+                return asdict(client.invoke(tool.name, arguments))
+            except AgentCommerceError as exc:
+                raise ToolException(str(exc)) from exc
+
+        async def arun(**arguments: Any) -> dict[str, Any]:
+            try:
+                return asdict(await client.ainvoke(tool.name, arguments))
+            except AgentCommerceError as exc:
+                raise ToolException(str(exc)) from exc
+
+        return StructuredTool(
+            name=tool.name,
+            description=tool.description,
+            args_schema=tool.input_schema,
+            func=run,
+            coroutine=arun,
+            handle_tool_error=True,
+            metadata={"needs_approval": tool.needs_approval},
+        )

langchain_agent_commerce-0.1.0/tests/test_e2e_langchain.py

@@ -0,0 +1,44 @@
+"""End-to-end: the toolkit's tools against a live gateway and chain, no language model."""
+
+import re
+
+import pytest
+from acg_e2e import Stack, enabled, usdc
+from langchain_agent_commerce import AgentCommerceToolkit
+
+pytestmark = [enabled, pytest.mark.e2e]
+
+
+@pytest.fixture(scope="module")
+def stack():
+    return Stack()
+
+
+def tool_of(stack, **limits):
+    tools = {t.name: t for t in AgentCommerceToolkit(**stack.client_kwargs(**limits)).get_tools()}
+    return tools[stack.resource]
+
+
+def test_price_within_limit_pays_once(stack):
+    tool = tool_of(stack)
+    before = stack.balance()
+    result = tool.invoke({})
+    assert isinstance(result, dict), result
+    assert result["status"] == 200
+    payment = result["payment"]
+    assert payment["success"] is True
+    assert re.fullmatch(r"0x[0-9a-fA-F]{64}", payment["transaction"])
+    assert stack.wait_for_balance(before - stack.price) == before - stack.price
+    assert stack.transaction_succeeded(payment["transaction"])
+    print(f"\nE2E langchain tx {payment['transaction']} balance {before} -> {before - stack.price}")
+
+
+def test_price_above_limit_pays_nothing(stack):
+    tool = tool_of(stack, max_per_call=usdc(stack.price // 2))
+    balance, receipts = stack.balance(), stack.receipt_ids()
+    output = tool.invoke({})
+    # The error comes back as tool output text, not as an exception
+    assert isinstance(output, str) and output.startswith("LIMIT_EXCEEDED")
+    assert stack.balance() == balance
+    assert stack.receipt_ids() == receipts
+    print(f"\nE2E langchain over-limit: {output}")

langchain_agent_commerce-0.1.0/tests/test_standard.py

@@ -0,0 +1,31 @@
+"""The standard langchain-tests unit suite for tools, run on a tool the toolkit builds."""
+
+import json
+from pathlib import Path
+
+import httpx
+from eth_account import Account
+from langchain_agent_commerce import AgentCommerceToolkit
+from langchain_tests.unit_tests import ToolsUnitTests
+
+CONFORMANCE = Path(__file__).resolve().parents[3] / "conformance"
+SUITE = json.loads((CONFORMANCE / "scenarios.json").read_text())
+RESOURCES = json.loads((CONFORMANCE / "fixtures" / "resources.json").read_text())
+
+
+class TestAgentCommerceToolStandard(ToolsUnitTests):
+    @property
+    def tool_constructor(self):
+        toolkit = AgentCommerceToolkit(
+            gateway_url="https://merchant.example.com",
+            signer=Account.from_key(SUITE["testSignerPrivateKey"]),
+            networks=["eip155:84532"],
+            max_per_call="0.05",
+            max_per_day="1.00",
+            transport=httpx.MockTransport(lambda request: httpx.Response(200, json=RESOURCES)),
+        )
+        return next(tool for tool in toolkit.get_tools() if tool.name == "weather_basic")
+
+    @property
+    def tool_invoke_params_example(self):
+        return {"city": "Berlin"}

langchain_agent_commerce-0.1.0/tests/test_toolkit.py

@@ -0,0 +1,209 @@
+"""Mapping tests: tool type, name, description, schema and approval. No payment logic lives here."""
+
+import base64
+import json
+from pathlib import Path
+
+import httpx
+import pytest
+from eth_account import Account
+from langchain.agents import create_agent
+from langchain.agents.middleware import HumanInTheLoopMiddleware
+from langchain_agent_commerce import AgentCommerceToolkit
+from langchain_core.language_models.fake_chat_models import GenericFakeChatModel
+from langchain_core.messages import AIMessage, ToolMessage
+from langchain_core.tools import StructuredTool
+from langgraph.checkpoint.memory import InMemorySaver
+from langgraph.types import Command
+
+CONFORMANCE = Path(__file__).resolve().parents[3] / "conformance"
+SUITE = json.loads((CONFORMANCE / "scenarios.json").read_text())
+RESOURCES = json.loads((CONFORMANCE / "fixtures" / "resources.json").read_text())
+PAYMENT_REQUIRED = (CONFORMANCE / "fixtures" / "payment-required.json").read_bytes()
+SIGNER = Account.from_key(SUITE["testSignerPrivateKey"])
+
+
+class Gateway:
+    """Discovery from the shared fixture; invocations answer 402, which the price limit then refuses."""
+
+    def __init__(self):
+        self.requests = []
+
+    def __call__(self, request):
+        self.requests.append(request)
+        if request.method == "GET":
+            return httpx.Response(200, json=RESOURCES)
+        if request.url.path.endswith("/weather_basic/invoke"):
+            return httpx.Response(200, json={"ok": True})
+        return httpx.Response(402, headers={"PAYMENT-REQUIRED": base64.b64encode(PAYMENT_REQUIRED).decode()})
+
+    def invocations(self):
+        return [r for r in self.requests if r.method == "POST"]
+
+
+def make_toolkit(gateway, **overrides):
+    return AgentCommerceToolkit(
+        **{
+            "gateway_url": "https://merchant.example.com",
+            "signer": SIGNER,
+            "networks": ["eip155:84532"],
+            "max_per_call": "0.005",
+            "max_per_day": "1.00",
+            "transport": httpx.MockTransport(gateway),
+            **overrides,
+        }
+    )
+
+
+def test_tools_map_the_core_descriptions():
+    toolkit = make_toolkit(Gateway())
+    tools = toolkit.get_tools()
+    described = toolkit.client.list_tools()
+    assert (
+        [t.name for t in tools]
+        == [d.name for d in described]
+        == ["report", "weather_basic", "no_description", "no_schema"]
+    )
+    for tool, expected in zip(tools, described):
+        assert isinstance(tool, StructuredTool)
+        assert tool.description == expected.description
+        assert tool.args_schema == expected.input_schema
+        assert tool.metadata == {"needs_approval": expected.needs_approval}
+        assert tool.func is not None and tool.coroutine is not None
+        assert tool.handle_tool_error is True
+
+
+@pytest.mark.parametrize(
+    ("approval", "gated"),
+    [
+        ("paid", {"report", "no_description"}),
+        ("always", {"report", "weather_basic", "no_description", "no_schema"}),
+        ("never", set()),
+    ],
+)
+def test_approval_middleware_gates_the_tools_needing_approval(approval, gated):
+    toolkit = make_toolkit(Gateway(), approval=approval)
+    tools = toolkit.get_tools()
+    middleware = toolkit.approval_middleware()
+    assert isinstance(middleware, HumanInTheLoopMiddleware)
+    assert set(middleware.interrupt_on) == gated == {t.name for t in tools if t.metadata["needs_approval"]}
+    for name, config in middleware.interrupt_on.items():
+        assert config["allowed_decisions"] == ["approve", "edit", "reject"]
+        assert next(t for t in tools if t.name == name).description in config["description"]
+
+
+def test_approval_middleware_discovers_when_get_tools_was_not_called():
+    gateway = Gateway()
+    toolkit = make_toolkit(gateway)
+    assert set(toolkit.approval_middleware().interrupt_on) == {"report", "no_description"}
+    assert [r.method for r in gateway.requests] == ["GET"]
+
+
+def test_construction_errors_surface_from_the_core():
+    with pytest.raises(TypeError):
+        AgentCommerceToolkit(
+            gateway_url="https://x", signer="0xabc", networks=["eip155:84532"], max_per_call="1", max_per_day="1"
+        )
+
+
+class ScriptedModel(GenericFakeChatModel):
+    def bind_tools(self, tools, **kwargs):
+        return self
+
+
+def tool_call(name, call_id="call_1"):
+    return AIMessage(content="", tool_calls=[{"name": name, "args": {}, "id": call_id}])
+
+
+def agent_of(toolkit, calls, **kwargs):
+    model = ScriptedModel(messages=iter([*calls, AIMessage(content="done")]))
+    return create_agent(model=model, tools=toolkit.get_tools(), **kwargs)
+
+
+def test_tool_error_reaches_the_model_as_text():
+    # The README example: create_agent(model=..., tools=toolkit.get_tools())
+    gateway = Gateway()
+    agent = agent_of(make_toolkit(gateway), [tool_call("report")])
+    result = agent.invoke({"messages": [("user", "report please")]})
+    message = next(m for m in result["messages"] if isinstance(m, ToolMessage))
+    assert message.status == "error"
+    assert message.content.startswith("LIMIT_EXCEEDED")
+    assert result["messages"][-1].content == "done"
+    assert not [r for r in gateway.requests if "payment-signature" in r.headers]
+
+
+async def test_agent_runs_async_tools():
+    agent = agent_of(make_toolkit(Gateway()), [tool_call("weather_basic")])
+    result = await agent.ainvoke({"messages": [("user", "weather")]})
+    message = next(m for m in result["messages"] if isinstance(m, ToolMessage))
+    assert json.loads(message.content) == {"status": 200, "body": {"ok": True}, "payment": None}
+
+
+@pytest.mark.parametrize(
+    ("decision", "invoked", "tool_output"),
+    [
+        ({"type": "reject", "message": "too expensive"}, ["weather_basic"], "too expensive"),
+        # Approved: the paid tool runs and the gateway is asked (the 0.005 limit then refuses the price)
+        ({"type": "approve"}, ["weather_basic", "report"], "LIMIT_EXCEEDED"),
+    ],
+)
+def test_a_turn_with_a_paid_tool_call_pauses_until_a_human_decides(decision, invoked, tool_output):
+    gateway = Gateway()
+    toolkit = make_toolkit(gateway)
+    config = {"configurable": {"thread_id": "t1"}}
+    calls = [{"name": "weather_basic", "args": {}, "id": "c1"}, {"name": "report", "args": {}, "id": "c2"}]
+    agent = agent_of(
+        toolkit,
+        [AIMessage(content="", tool_calls=calls)],
+        middleware=[toolkit.approval_middleware()],
+        checkpointer=InMemorySaver(),
+    )
+    paused = agent.invoke({"messages": [("user", "go")]}, config, version="v2")
+    assert [a["name"] for a in paused.interrupts[0].value["action_requests"]] == ["report"]
+    # The turn is paused as a whole: nothing was invoked yet
+    assert gateway.invocations() == []
+
+    done = agent.invoke(Command(resume={"decisions": [decision]}), config=config, version="v2")
+    contents = [m.content for m in done.value["messages"] if isinstance(m, ToolMessage)]
+    assert any(tool_output in c for c in contents)
+    # LangChain runs the calls of one turn in parallel, so their order is not fixed
+    assert sorted(r.url.path.split("/")[3] for r in gateway.invocations()) == sorted(invoked)
+
+
+def tools_of(gateway, **overrides):
+    return {t.name: t for t in make_toolkit(gateway, **overrides).get_tools()}
+
+
+def test_arguments_reach_the_gateway_as_the_json_body_on_the_sync_path():
+    gateway = Gateway()
+    result = tools_of(gateway)["weather_basic"].invoke({"city": "Berlin"})
+    assert result == {"status": 200, "body": {"ok": True}, "payment": None}
+    assert [json.loads(r.content) for r in gateway.invocations()] == [{"city": "Berlin"}]
+
+
+async def test_arguments_reach_the_gateway_as_the_json_body_on_the_async_path():
+    gateway = Gateway()
+    result = await tools_of(gateway)["weather_basic"].ainvoke({"city": "Berlin"})
+    assert result == {"status": 200, "body": {"ok": True}, "payment": None}
+    assert [json.loads(r.content) for r in gateway.invocations()] == [{"city": "Berlin"}]
+
+
+async def test_a_failing_async_tool_returns_text_instead_of_raising():
+    output = await tools_of(Gateway())["report"].ainvoke({})
+    assert output == "LIMIT_EXCEEDED: Price 0.01 USDC exceeds the per-call limit of 0.005 USDC"
+
+
+def test_a_failing_sync_tool_returns_text_instead_of_raising():
+    output = tools_of(Gateway())["report"].invoke({})
+    assert output == "LIMIT_EXCEEDED: Price 0.01 USDC exceeds the per-call limit of 0.005 USDC"
+
+
+def test_a_turn_with_only_free_tool_calls_runs_without_a_pause():
+    gateway = Gateway()
+    toolkit = make_toolkit(gateway)
+    agent = agent_of(
+        toolkit, [tool_call("weather_basic")], middleware=[toolkit.approval_middleware()], checkpointer=InMemorySaver()
+    )
+    done = agent.invoke({"messages": [("user", "go")]}, {"configurable": {"thread_id": "t2"}}, version="v2")
+    assert done.interrupts == ()
+    assert [r.url.path.split("/")[3] for r in gateway.invocations()] == ["weather_basic"]