Skip to main content

recusal-langchain

The Recusal gate for a LangChain create_agent agent: every tool call the agent proposes is judged by your policy before the tool runs, and a refused call never runs.

This is a separate distribution from recusal. The kernel has zero runtime dependencies and a frozen compatibility perimeter; this package carries the LangChain dependency and its own version, so a LangChain release never forces a release of the kernel.

A create_agent agent executes its tools through a LangGraph ToolNode, so this package adds no decision logic of its own. It wraps the gate of recusal-langgraph as LangChain middleware and depends on that package.

Install it from PyPI. recusal-langgraph, which this package requires, comes with it:

pip install recusal-langchain

Requires Python 3.10+, recusal>=0.14.0, recusal-langgraph>=0.1.0 and langchain>=1.4.3. It is tested on every pull request against exactly langchain==1.4.3 with langgraph==1.2.12 and langchain-core==1.6.5, and weekly against the newest releases.

Use

from langchain.agents import create_agent
from langchain_core.tools import tool
from recusal import Finding
from recusal_langchain import gate_middleware


@tool
def run_sql(sql: str) -> str:
    """Run a SQL statement."""
    ...


def policy(tool_name, tool_input):
    sql = tool_input.get("sql", "")
    if tool_name == "run_sql" and sql.lstrip().upper().startswith("DELETE"):
        return [Finding.fail("no_deletes", severity="CRITICAL", message="DELETE is not allowed")]
    return []


agent = create_agent(model=model, tools=[run_sql], middleware=[gate_middleware(policy)])

A refused call is answered with an error ToolMessage carrying Recusal's reason, and its tool does not run. A policy that raises refuses the call (fail closed). For agent.ainvoke, use agate_middleware(policy); the sync gate alone raises there.

List the middleware last. The first middleware in the list is the outermost, so anything listed after the gate runs between the gate and the tool.

Put every decision on the record

from recusal.audit import AuditLog
from recusal_langchain import audited_gate_middleware

log = AuditLog(path="decisions.jsonl")
agent = create_agent(
    model=model, tools=[run_sql], middleware=[audited_gate_middleware(policy, log)]
)

audited_agate_middleware is the async form. Each call the gate sees, allowed or refused, is one hash-chained entry labeled langchain.create_agent with LangChain's tool call id and a SHA-256 fingerprint of the arguments (never the arguments). If the log cannot be written the call is refused. Check the log with recusal audit verify decisions.jsonl.

What the gate does not see

The gate judges, and records, inside the tool's own lifecycle. A middleware listed after it that rewrites the arguments is still judged and recorded as rewritten. A middleware listed after it that swaps the tool object, or answers in the tool's place, removes the judging copy, and that call is neither judged nor recorded. That is why the gate goes last.

Everything recusal-langgraph refuses before the policy runs is refused here too: a tool that overrides the standard execution lifecycle, input that does not validate, and a callable with a parameter its schema omits.

Compatibility

This package is outside the kernel's frozen perimeter (STABILITY.md, Integrations). Its public names are the ones in recusal_langchain.__all__. It uses only the public names of recusal-langgraph.

A runnable offline demonstration, with a scripted model and no API key, is examples/langchain_agent_gate.py and examples/langchain_agent_audit.py.

Metadata

Release files for recusal-langchain 0.1.1

For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.

Source distribution (sdist)

Source distribution for recusal-langchain 0.1.1
File Size Uploaded Provenance Actions
recusal_langchain-0.1.1.tar.gz 10.3 kB With provenance Details for recusal_langchain-0.1.1.tar.gz

Built distribution (wheel)

Table of built distributions (wheels) for recusal-langchain 0.1.1
File Interpreter ABI Platform Actions
recusal_langchain-0.1.1-py3-none-any.whl Python 3 none any Details for recusal_langchain-0.1.1-py3-none-any.whl

Total release size: 20.2 kB

Release files / recusal_langchain-0.1.1.tar.gz

Download URL recusal_langchain-0.1.1.tar.gz
Size 10.3 kB
Tags Source
SHA-256 checksum
How to use checksums
2bfd9b3a5e889fa38f1b81fcf222b99c52f14c8733bbac61306ecd3f82dbd98f
BLAKE2b-256 checksum
How to use checksums
89d0b87b768c2f4125d7d2dc64d9f470c0a8683d7e60b37aba2660d313bea801
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
Yes
Uploaded via twine/7.0.0 CPython/3.13.16

Provenance

Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.

PyPI Publish Attestation

PyPI verified that this artifact, at this checksum, originated from the publisher listed below.

Signed by GitHub Actions, verified by PyPI on Nov 14, 2026.

Transparency log

Release files / recusal_langchain-0.1.1-py3-none-any.whl

Download URL recusal_langchain-0.1.1-py3-none-any.whl
Size 9.9 kB
Tags Python 3
SHA-256 checksum
How to use checksums
c1e5ee1abd10de0fa80bb0e1b4fc9d5bb5784c1393def88fb7a02ae9ef5fedfa
BLAKE2b-256 checksum
How to use checksums
5717706486af9cfba3d35ccb37c0c8bdb83aa1fc841dc42692452113ee0b41e4
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
Yes
Uploaded via twine/7.0.0 CPython/3.13.16

Provenance

Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.

PyPI Publish Attestation

PyPI verified that this artifact, at this checksum, originated from the publisher listed below.

Signed by GitHub Actions, verified by PyPI on Nov 14, 2026.

Transparency log

Security for recusal-langchain 0.1.1

Provenance

Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.

Full provenance

Both files in this release have been uploaded with provenance metadata.

Select from 2 files

Attestation for recusal_langchain-0.1.1.tar.gz

PyPI Publish Attestation

PyPI verified that this artifact, at this checksum, originated from the publisher listed below.

Signed by GitHub Actions, verified by PyPI on Nov 14, 2026.

Transparency log

A note on package security

PyPI is a repository for distributing packages, not a service for auditing them. While third-party security researchers and our staff do their best to detect and remove malicious packages, PyPI cannot guarantee the quality, security or suitability of any given package.

To learn more about protecting yourself from malicious actors, visit our package security documentation.

Release history Release notifications | RSS feed

This release

0.1.1 This release

2 release files Full provenance

Anthropic, PBC Visionary sponsor Bloomberg Visionary sponsor Hudson River Trading Visionary sponsor Meta Visionary sponsor NVIDIA Visionary sponsor Microsoft Sustainability sponsor Depot Continuous Integration AWS Cloud computing and Security Sponsor Datadog Monitoring Fastly CDN Google Download Analytics Sentry Error logging StatusPage Status page