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)
| 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)
| File | Interpreter | ABI | Platform | Actions Reset |
|---|---|---|---|---|
| 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 logRelease 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 logSecurity 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.
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 logA 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.