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.

Status: not yet published to PyPI. Until it is, install both from the repository, recusal-langgraph first since this package requires it:

pip install "recusal-langgraph @ git+https://github.com/philpaz/recusal#subdirectory=adapters/langgraph"
pip install "recusal-langchain @ git+https://github.com/philpaz/recusal#subdirectory=adapters/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.0

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.0
File Size Uploaded Provenance Actions
recusal_langchain-0.1.0.tar.gz 10.3 kB With provenance Details for recusal_langchain-0.1.0.tar.gz

Built distribution (wheel)

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

Total release size: 20.3 kB

Release files / recusal_langchain-0.1.0.tar.gz

Download URL recusal_langchain-0.1.0.tar.gz
Size 10.3 kB
Tags Source
SHA-256 checksum
How to use checksums
2819b62d02b5e1d1565ac07b9eb24d3f69ccdf4fd4a3c067badd2f1e1bac932c
BLAKE2b-256 checksum
How to use checksums
b139322d1f526d22a3feed66685c71ae970919606d72c01ef7f24d2c05349e69
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.0-py3-none-any.whl

Download URL recusal_langchain-0.1.0-py3-none-any.whl
Size 10.0 kB
Tags Python 3
SHA-256 checksum
How to use checksums
3fd12e45044c419e5f40cc1b6cd4331dedde60d268c6350ac5d609ddc639c657
BLAKE2b-256 checksum
How to use checksums
7b2a3e9b2d28cd999dad0f624ca0ca857a03ad811192b7942ea5c28542fd68ea
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.0

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.0.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.0 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