immiscible

Govern what your AI agents spend, share and do, from Python. Before a tool runs, the agent asks Immiscible; Immiscible checks the mandates a person wrote, asks that person when it should, and hands back a signed receipt. Spend control, approvals and TokenOps for the OpenAI Agents SDK, LangChain, LangGraph and MCP. Standard library only: urllib, json, hashlib and a pure-Python Ed25519 verifier. Python 3.9+. Type hints throughout (py.typed). Fails closed.

pip install immiscible

from immiscible import Immiscible, tool_action

immiscible = Immiscible()                        # IMMISCIBLE_AGENT_KEY, IMMISCIBLE_URL
run = immiscible.run()                           # one trace and one session per task

with run.guard(tool_action("deploy", {"service": "api"}, domain="mycompany.com")):
    deploy()

guard asks, waits for a person if one is asked, runs your block only if allowed, and settles completed (or failed if it raised). A refusal raises ImmiscibleDeniedError with plain-English reasons; your block never ran. As a decorator it takes a function that maps the call to an action, and works on async def too.

Set up a project in one command with npx immiscible init (it writes IMMISCIBLE_URL and IMMISCIBLE_AGENT_KEY to .env). Quickstart: immiscible.fly.dev/docs/quickstart. Answers to common questions: immiscible.fly.dev/docs/answers. SDKs: immiscible.fly.dev/docs/sdks. API: immiscible.fly.dev/docs/api. JavaScript: @immiscible/sdk on npm. MIT licence.

The client

Errors

Everything the SDK raises on purpose is an ImmiscibleError, with status, type, body and request_id (quote it when asking for help). HTTP failures use a subclass by status: ImmiscibleAuthenticationError (401), ImmiscibleInvalidRequestError (400 or 422, with errors per field), ImmiscibleRateLimitError (429, with retry_after in seconds), ImmiscibleIdempotencyConflictError (409, the same key with a different body) and ImmiscibleConnectionError (unreachable or timed out). Refusals are ImmiscibleDeniedError, ImmiscibleApprovalRequiredError and ImmiscibleApprovalTimeoutError.

Integrations

from immiscible.integrations import guard_tools, guard_langchain_tools, guarded

Setups for each framework: immiscible.fly.dev/docs/sdks.

Receipts

from immiscible import fetch_jwks, verify_receipt

jwks = fetch_jwks("https://immiscible.example")                  # pin: fetch once, store with your config
r = verify_receipt(token, "https://immiscible.example", jwks=jwks, online=True,
                   expect={"amount": 6420, "currency": "GBP", "merchant": "ocado.com"})

The same checks as the TypeScript SDK, with a pure-Python Ed25519 verifier checked against RFC 8032 and against Node's signatures.

Testing

python3 -m unittest discover -s tests -t .

immiscible.testing.start_fake() is a stdlib fake server (real Ed25519 receipts, a fake gateway and model, the MCP proxy, a person's approvals) for your own tests. tests/test_frameworks.py runs against the real openai, openai-agents, langchain-core and langgraph when they are installed; tests/test_cross_language.py runs against the TypeScript SDK's fake when Node is available.

Crypto payments: decide, then sign

Immiscible never holds keys or signs. decide_then_sign asks first and calls your wallet only after an allow whose signed receipt covers the exact transfer; x402_request does the same for HTTP 402 (x402 v1 and v2) resources.

from immiscible import Immiscible
from immiscible.crypto import decide_then_sign, x402_request

decide_then_sign(Immiscible(), {"asset": "USDC", "network": "base", "amount": "12.50", "recipient": "0x..."},
                 lambda decision: {"txHash": wallet.send()})
status, headers, body = x402_request(Immiscible(), "https://api.example.com/report", pay=my_x402_signer)

Amounts are decimal strings, never floats. See crypto payments and x402.