crewai-x402-sagg

A CrewAI tool that pays for SAGG chat-completion requests per-request, via the x402 protocol (a signed crypto micropayment) instead of an API key - the same idea as this repo's sibling package, langchain-x402-sagg, adapted to CrewAI's own tool idiom.

Status: testnet only (Base Sepolia) - this package specifically has never been run against mainnet (the sibling langchain-x402-sagg has, with one real successful payment; this one shares its payment logic but has not itself been exercised there). Not published to PyPI or GitHub - prepared for review, not distributed.

Same architectural decision as the LangChain package, still justified here

Like langchain-x402-sagg, this package reimplements EIP-712/EIP-3009 signing natively in Python (eth_account) rather than wrapping the existing Go client (x402module/poc) via a subprocess/HTTP bridge. The reasoning carries over unchanged: EIP-712 is an open standard with a mature Python implementation already, and a Go-binary bridge would add real packaging/distribution friction for what should be a lightweight, pip install-able tool. See the LangChain package's own README for the fuller comparison - it wasn't re-litigated here since nothing about CrewAI specifically changes that calculus.

What IS adapted, not copied: CrewAI's own tool-definition idiom. Verified directly against CrewAI's official docs (docs.crewai.com/en/learn/create-custom-tools) rather than assumed from the LangChain package's own pattern - CrewAI's simplest, most idiomatic shape for a single-string-argument tool is a plain function decorated with crewai.tools.tool("Name"), not a pydantic BaseTool subclass (that also exists, for tools needing a structured multi-field schema) and not LangChain's StructuredTool.from_function. tool.py uses the @tool-decorated-function form.

Known environment issue - disclosed honestly, not routed around

This package's own development environment could not get a working crewai install to actually run tool.py against. The only crewai version this environment's package index served (0.11.2) eagerly imports a legacy langchain<0.2.0 dependency chain at import crewai, which pins numpy<2 - a version with no prebuilt wheel for Python 3.14 (this environment's Python), so installing it requires building numpy from source, which in turn needs a C/C++ compiler toolchain not present in this environment. Installing a full build toolchain just to import a Tool base class was judged disproportionate effort for this task, not attempted.

What this does and does not affect: client.py/signer.py - the actual x402 payment logic (signing, the 402 challenge/retry flow) - depend only on eth_account/requests, not on crewai at all, and are fully installable, unit- tested, AND live-tested in this same environment (see below) - a real, working, independently-verified payment client. tool.py's own ~15-line @tool-decorated wrapper around that client was written and reviewed against CrewAI's real, current documentation, but could not itself be imported/instantiated in this session to confirm it runs against an actual crewai Agent. Given crewai's own dependency tree is heavy and evidently version-sensitive, this package deliberately keeps crewai as an OPTIONAL install extra (pip install crewai-x402-sagg[crewai]) rather than a hard dependency - so the core payment logic stays usable even in an environment where the full crewai framework itself can't install, which is exactly the situation this session hit.

If you have a working crewai environment, tool.py's own ~15 lines are short enough to read and verify by inspection against the docs snippet quoted above; this README does not claim more live confidence in that specific file than was actually established.

Installation

pip install -e .              # core payment client only
pip install -e ".[crewai]"    # + the actual crewai framework, if your environment supports it

Usage

from crewai_x402_sagg.tool import make_sagg_x402_tool
from crewai import Agent

tool = make_sagg_x402_tool(
    private_key="0x...",              # a Base Sepolia testnet EVM private key, funded with testnet USDC
    sagg_url="https://your-sagg-gateway.example.com",
)

agent = Agent(
    role="Researcher",
    goal="...",
    backstory="...",
    tools=[tool],
)

Configuration

Same as langchain-x402-sagg - see that package's README for the full table (private_key, sagg_url, model, max_amount_atomic, network).

Testing

pip install -e ".[dev]"
pytest tests/test_signer.py tests/test_client.py -v   # fast, no network - signing + network-validation logic

Live end-to-end (moves real testnet funds, opt-in):

SAGG_X402_TEST_PRIVATE_KEY=0x... \
SAGG_X402_TEST_URL=http://localhost:18080 \
RUN_LIVE_X402_TEST=1 \
pytest tests/test_live_sagg_x402.py -v -s

This exercises SaggX402Client directly (the same code tool.py calls) - not the CrewAI-specific wrapper itself, per the environment limitation above. Run for real during this package's own development against a locally-running SAGG gateway instance (Base Sepolia, real facilitator, real on-chain settlement): 200 OK, a real ceiling settlement and a real refund, both independently confirmed on-chain (eth_getTransactionReceipt, status: 0x1 for both) rather than trusted from the gateway's own response.

Security

Same underlying client as langchain-x402-sagg (private key held in plain Python process memory, max_amount_atomic a real enforced ceiling that only protects against this client's own over-payment, not a malicious server's pricing below that ceiling), including the same network-validation check: post_with_payment refuses to sign, before any signature is produced, if the server's own 402 challenge names a different network than this client was configured for - added after a real failure discovered in the sibling package (a client signing with the wrong chain id for the server it was actually talking to). Unlike that sibling package, this one has only ever been run against testnet - see the Status note above.

What this package does NOT do

• Publish itself anywhere (no PyPI, no GitHub).
• Guarantee it runs against any specific crewai version's Agent/Tool runtime end-to-end - see "Known environment issue" above.
• Support streaming responses or provider failover - a minimal, first-version client.