Skip to main content

norcaster-langchain

For an agent built with LangChain. Before every call the agent makes to the AI provider, it asks Norcaster for a decision. Norcaster answers from the app's rules and keeps a record of every answer. The agent then calls the provider itself: your app is not re-pointed, and your provider keys stay where they are.

Norcaster's decision What the agent does
allow Calls the provider with the conversation as it is.
hide Calls the provider with the version Norcaster returned, with the sensitive data hidden.
block Does not call the provider. The run stops with an error that names the decision and the record.

It can also ask about the model's answer before the agent uses it: see Answer checks.

Status: new. Tested with LangChain 1.2.11 and 1.5.0.

Set up

You need a Norcaster key with the runs:write scope and the id of the app in Norcaster.

  1. Install the adapter into the Python environment that runs your agent. It brings the Norcaster SDK (norcaster) with it:

    pip install norcaster-langchain
    
  2. Add the middleware to your agent. It is one entry in the list, placed last:

    import os
    
    from langchain.agents import create_agent
    from norcaster_langchain import NorcasterCheckMiddleware
    from norcaster import NorcasterCloudClient
    
    norcaster = NorcasterCloudClient(os.environ["NORCASTER_API_KEY"], "https://api.norcaster.com")
    
    agent = create_agent(
        model,
        tools,
        middleware=[NorcasterCheckMiddleware(norcaster, deployment_id="<the app's id>")],
    )
    
  3. Run the agent once. The model's answer carries the record's id (message.response_metadata["norcaster"]["receipt_id"]), and the same call is in the app's records in Norcaster, marked Checked.

examples/agent.py is a small agent that shows allow, hide, block and what happens when Norcaster can't be reached. Its provider is a stand-in inside the script, so only the checks leave your machine.

Put the middleware last. LangChain runs the list from the outside in, so a middleware placed after this one can change the conversation after it was checked.

What the record shows

The app asked Norcaster before it called the provider.

What it does not show:

  • What the agent sent afterwards. Norcaster does not see the provider call. The record holds a SHA-256 of the conversation as the adapter sent it to Norcaster (the text and the tool calls, as chat messages). It is not a hash of the bytes LangChain sent to the provider.
  • That every call was checked. Only model calls that go through this middleware are. See below.
  • Anything about the provider's answer, unless answer checks are on. Then the record of the answer shows your app asked about a text: not that the text was the provider's answer, or what your app did with it afterwards.

If you need a record that nothing reached the provider unchecked, send the app's traffic through the Norcaster gateway instead.

The conversation is sent to Norcaster to be checked. If your data may not leave your network, this adapter does not change that; a Norcaster you host yourself does.

What is checked

Every model call of the agent, not only the first. An agent that uses a tool three times in a row makes four model calls, and each one is checked before it is made. Each check covers everything that call sends:

  • the system prompt and the user's messages;
  • the agent's earlier answers;
  • the arguments of tool calls from earlier steps;
  • the results of tools, which is how a secret a tool read is stopped before it goes to the provider.

A streamed call is checked before the stream starts. Sync and async runs are checked the same way.

What is not checked:

  • The model's answer, and the tool calls it asks for, when it asks for them, unless you turn on answer checks. Without them a tool runs with the arguments the model wrote, and Norcaster reads those arguments at the next model call, with the rest of the conversation, after the tool has run.
  • Tool definitions, the model's name and its settings.
  • The model's own reasoning that some providers send back with the conversation. Providers sign it, so it is sent on as it is and Norcaster is not asked about it.
  • Model calls made outside this middleware: another middleware that calls a model itself (summarization, tool selection), a sub-agent built without the middleware, a tool that calls a model, a call your code makes directly.
  • An extra_body or model_kwargs chosen per run, as a configurable field (init_chat_model(configurable_fields=...), configurable_fields(...)): the middleware can't see it. Don't make either one configurable on a model the agent checks.

Images, files and audio in a message meet your app's rules for them, the same rules the Norcaster gateway applies (allow, warn or block, and limits on how many, how large and which types). Each is checked as the OpenAI chat part it would be, and Norcaster gets a description of each inline one (the SHA-256 of its bytes, its size, media type and pixel size), never the file. Nothing reads what it shows, and the record lists it as not read. A hide changes only the text: the files go to the model as they were. This takes LangChain's own image, file and audio blocks, OpenAI's and Anthropic's. Requires norcaster 0.1.5 or later, and a Norcaster from 19 November 2026 or later.

What is refused. A call that holds anything a check can't read is not sent: a file the OpenAI chat shape can't hold (an image by file id, a document by URL, a plain-text document, video, audio other than WAV and MP3, a file in a tool's result), or the result of a tool the provider runs itself. The run stops with NorcasterCannotCheck and Norcaster is not asked. This is so that nothing goes to the provider unread.

The same goes for a model whose settings carry content of their own:

  • messages, input, instructions or prompt in extra_body (on the model, on a bound model, or in a middleware's model_settings);
  • instructions or a stored prompt set on the model;
  • a predicted output (prediction, OpenAI's Predicted Outputs) in model_kwargs, in extra_body, on a bound model or in a middleware's model_settings. It is usually the same file a message holds, and a check doesn't read it, so a hide in that file would go out unhidden there.

The OpenAI client would send that beside or in place of the checked messages. Put it in the agent's system prompt or messages instead, and leave prediction out.

When the decision is hide

Norcaster's hidden text is written into a copy of the conversation, in every place it lives: the message's text, the tool call's arguments, the tool's result. The provider gets the copy. The conversation your app keeps is unchanged.

Two things to know:

  • The model sees the placeholder, not the value. If it then calls a tool with the hidden value, the tool gets the placeholder.
  • If the hidden version can't be written back exactly, the call is not sent (NorcasterCannotCheck). It is never sent with the original text.

Answer checks

Off unless you turn them on. With check_output=True the middleware also asks Norcaster about each of the model's answers, after every model call of the run and before the agent uses it (POST /v1/check/output): its text, and the tool calls it asks for (each tool's name and its arguments), so before the agent's tools node runs any of them:

NorcasterCheckMiddleware(norcaster, deployment_id="<the app's id>", check_output=True)
Norcaster's decision on the answer What the agent gets
allow The answer as the model wrote it.
hide A copy with Norcaster's hidden text, and each tool call's arguments with the sensitive values hidden, in every place the message keeps them (tool_calls, the provider's content blocks, additional_kwargs). The tool runs with those arguments. The answer's token list (logprobs), which spells out the original words, is left out.
block Nothing. The run stops with NorcasterBlocked, about == "answer". A tool the answer asked for does not run.

The answer's check is recorded under the same request as the check before the call, so the app's records show one call with two decisions. Its receipt is on the answer, under response_metadata["norcaster"]["answer"]. Each model call that answers with text or tool calls adds one more round trip to Norcaster, before any tool runs.

The app's rules must cover answers. If they don't, Norcaster refuses the check: NorcasterCheckRefused with code output_rules_off and about == "answer". It happens after the provider has answered, on every call, until the rules cover answers or check_output is off.

What is read: the answer's text, which is its string content or its text blocks run together, and its tool calls: tool_calls (each tool's name and its args as compact JSON), the ones LangChain couldn't parse (invalid_tool_calls, their arguments as the text the model wrote) and OpenAI's older function_call. An answer that is only tool calls is asked about too.

When a tool call is hidden: the tool runs with placeholders in place of the sensitive values, in JSON of the same shape (the same keys and value types; the tool's name never changes). A placeholder can change what a tool does: a mail tool would get [REDACTED: EMAIL] as the address. If a tool can't run with a placeholder, treat hide as block in that tool. A hide that can't be written into every copy of the call withholds the answer (NorcasterCannotCheck).

What is handed on unread:

  • The model's reasoning (thinking blocks). Providers sign it, so it is handed on as it is, after a hide too: it can still hold what the hide took out of the text.
  • A refusal kept outside the text (additional_kwargs["refusal"]), and usage.
  • Provider metadata other than logprobs. Citations keep their offsets into the original text.

What is withheld: an answer that holds an image, a file, audio, or any part of a kind the adapter doesn't know (results of tools the provider runs itself among them). It is never handed on unread: NorcasterCannotCheck, about == "answer". So is an answer that is hidden and was also parsed into a structured response, from its text (response_format with the provider's structured output) or from a tool call's arguments: the structured response holds the original words. Allowed, it is handed on.

The check engine in your own network reads tool calls too. An older engine refuses them (409 tool_calls_not_on_engine), and the answer is withheld.

An older norcaster SDK that can't ask about tool calls (0.1.1 or older; this adapter requires norcaster>=0.1.2, so only an SDK installed around that rule): an answer with tool calls is withheld (NorcasterCannotCheck), never handed on with its tool calls unread. Answers with text only are checked as before.

What the record shows: that the app asked about the answer and its tool calls, and which tools (never their arguments). Not what the agent then did, or which tools ran.

Streaming. LangChain tells callbacks about the model's answer inside the model call, before any middleware gets it back. So, with answer checks on:

  • stream_mode="messages" (alone or with other modes, sync or async): the model call is tagged nostream, and the stream carries each step's checked answer as one message at the end of the step, not token by token. LangChain still streams from the provider; your app gets the first words once the provider has finished and Norcaster has decided. "updates" and "values" work as before.
  • Refused before anything is sent (NorcasterCannotCheck): astream_events, astream_log, and a callback of your own that takes the answer as it is written (on_llm_new_token), set on the run or on the model.
  • Tracers (LangSmith) and other callbacks are still told about the provider's answer as it came when the model call ends (on_llm_end), as they are told about each step's messages before a hide. Don't hand the answer on from a callback.

When Norcaster can't be reached after the model answered, the answer is withheld: NorcasterUnreachable with about == "answer". With when_unreachable="let_through" the agent gets the answer, response_metadata["norcaster"]["answer"] says "decision": "unchecked", and Norcaster records it as an answer let through without a check, under the request it belongs to. When the request itself was let through, its answer is not asked about: the one record stands for the call.

Retry and fallback middleware placed before this one (ModelRetryMiddleware, ModelFallbackMiddleware) retry or fall back on a block too, so the provider is called again. Each try is checked and leaves its own records. The same holds for a blocked request.

A graph you built yourself

The middleware works with create_agent. A graph built by hand with LangGraph, or a plain chain, has no place for it: LangChain offers no hook around a model call there. Call the same check yourself, right before the node calls the model:

from norcaster_langchain import check_messages

def call_model(state):
    checked = check_messages(norcaster, state["messages"], deployment_id="<the app's id>")
    answer = model.invoke(checked.messages)          # the messages to send: hidden when told to
    return {"messages": [checked.stamp(answer)]}     # the answer, with the record's id on it

acheck_messages is the same for async code. A block raises NorcasterBlocked before the model is called.

Here the check happens only where you call it. A node that calls the model without it is not checked and leaves no record. Call the model with the checked messages and no other content: an extra_body or model_kwargs that holds messages, input, instructions, a prompt or a prediction would reach the provider unchecked, and here nothing refuses it.

To ask about the answer too, call check_answer on it before the node returns it:

from norcaster_langchain import check_answer, check_messages

def call_model(state):
    checked = check_messages(norcaster, state["messages"], deployment_id="<the app's id>")
    answer = model.invoke(checked.messages, config={"tags": ["nostream"]})
    return {"messages": [check_answer(norcaster, answer, checked, deployment_id="<the app's id>")]}

It returns the answer to use, with both receipts on it, and raises as the middleware does. acheck_answer is the same for async code. The nostream tag keeps stream_mode="messages" from sending the provider's answer before it is checked; the checked answer goes out when the node returns. Without it, a streamed graph hands on the provider's tokens first.

Settings

Setting Default What it is
client required Your NorcasterCloudClient. It holds the key and your Norcaster address.
deployment_id the key's app The app's id. Leave it out only when the key belongs to one app.
when_unreachable "block" "block" or "let_through". See below.
on_unchecked none Called every time a call is let through without a check.
timeout 10 Seconds to wait for Norcaster's answer.
check_output False Also ask about the text of each of the model's answers. See Answer checks.

These are the Norcaster SDK's own settings for a check, passed on unchanged. A wrong setting is refused when the middleware is built, so the app does not start with it.

One middleware per app. Each agent that is its own app in Norcaster gets its own deployment_id, so each has its own rules and its own records.

What your code gets

The record's id, on every answer. Each answer of the model carries the check that came before the call that produced it:

answer.response_metadata["norcaster"]
# {"decision": "hide", "receipt_id": "88bfb959-…", "content_sha256": "8cdc…", "rules_version": 3,
#  "decided_at": "2026-11-12T16:07:41.512+00:00", "request_id": "chk_…"}

With answer checks on, the answer's own check is under "answer", with the same keys:

answer.response_metadata["norcaster"]["answer"]
# {"decision": "allow", "receipt_id": "5d0c…", "content_sha256": "1f3a…", "rules_version": 3,
#  "decided_at": "2026-11-12T16:07:42.104+00:00", "request_id": "chk_…"}

It stays in the agent's messages and shows wherever you trace them. It never holds the conversation, the answer or the key.

An error when the call is not made, or the answer is not handed on. All of them are NorcasterCheckError, from the SDK. about says which: "request" (the provider was not called) or "answer" (the provider answered and the answer was withheld).

Error When
NorcasterBlocked The decision was block. It has code, reason, suggestion and receipt_id.
NorcasterUnreachable Norcaster could not be reached and the call was not let through.
NorcasterCheckRefused Norcaster refused the check: a wrong or revoked key, a missing scope, a stopped app, the rate limit, too much content, rules that don't cover answers (output_rules_off).
NorcasterCannotCheck The call or the answer holds something a check can't read, the hidden version could not be written back, or the run is streamed in a way that would hand on the answer before it is checked.

A block looks like this, and never repeats what was blocked:

NorcasterBlocked: Norcaster's decision was block (contextual_block). A secret or access credential
was detected in an earlier message in this conversation. The provider was not called.
Receipt: 8070b112-3270-45eb-ad0e-7cad5dbe55a0.

The error stops the agent's run. Catch it where you call the agent.

When Norcaster can't be reached

"Can't be reached" means no connection, no answer within timeout, or an error on Norcaster's side.

By default the call is blocked: NorcasterUnreachable, and the provider is not called. With answer checks on, an answer is withheld the same way (Answer checks).

when_unreachable="let_through" makes the call instead. Every call that is let through is recorded, each time:

  1. A warning in your app's log (logger norcaster.check), with the call's id and its SHA-256.
  2. Your on_unchecked function is called with it.
  3. On the model's answer: response_metadata["norcaster"] says "decision": "unchecked" and carries the id.
  4. In Norcaster, once it answers again: the next check that succeeds reports what was let through, and it shows in the app's records as Let through without a check.

The record holds a SHA-256 of the conversation, when it happened and why. It never holds the conversation itself. No rule ran on a call that was let through, and it is not counted as a check.

Know these limits before you turn it on:

  • A call that is let through goes to the provider as the agent wrote it. Nothing is hidden.
  • Calls waiting to be reported are kept in your app's memory. If the app stops before Norcaster answers again, your own log line is the only record. norcaster.report_unchecked() sends what is waiting; call it when your app shuts down.
  • At most 10,000 wait at a time. Past that, calls are blocked.
  • A refusal from Norcaster always blocks, whatever the setting.

Limits to know

  • Each model call is one check. An agent run with five model calls is five checks. A check draws on the same rate limit as a request through Norcaster's gateway: 600 a minute by default, shared by all of one person's keys, or by one service account's or agent's keys. Over the limit, Norcaster refuses and the call is blocked. Like gatewayed requests, checks don't count toward the plan's monthly request limit yet.
  • Each model call waits for Norcaster's answer. Measured against a local Norcaster: about 11 ms for a short prompt and about 19 ms for a 4 KB conversation, at the median. A hosted Norcaster adds the network round trip.
  • Each check sends the whole conversation so far, so the wait grows as the conversation does. More than 1,000,000 characters is refused.
  • Answer checks read text only, and add one round trip per model call that answers with text. A streamed answer reaches your app once the provider has finished and Norcaster has decided. See Answer checks.
  • Async runs: one Norcaster client per event loop. The SDK keeps one connection open for async checks, and it belongs to the event loop that first used it.

Develop

The tests need LangChain, LangChain's OpenAI package and the SDK from this repository (sdk/python). From this folder:

PYTHONPATH=src:../../sdk/python/src uv run --isolated --no-project --python 3.12 \
  --with "langchain==1.5.0" --with "langchain-openai>=1.0.0,<2" --with "httpx>=0.24" --with "pytest>=7" \
  python -m pytest -q
  • test/test_conversation.py: what is sent to Norcaster for each kind of message, and how a hidden version is written back.
  • test/test_agent.py: the middleware inside a real agent, with a stand-in model.
  • test/test_answer.py: answer checks, in an agent, in a streamed run, and by hand.
  • test/test_openai_wire.py: the same on LangChain's real OpenAI chat model, against a stand-in provider on 127.0.0.1, to show what goes over the wire.
  • test/test_example.py: the example agent.

Norcaster is a stand-in on 127.0.0.1 in all of them. No provider and no Norcaster API is called.

Metadata

Release files for norcaster-langchain 0.1.2

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

Source distribution (sdist)

Source distribution for norcaster-langchain 0.1.2
File Size Uploaded Provenance Actions
norcaster_langchain-0.1.2.tar.gz 55.0 kB Without provenance Details for norcaster_langchain-0.1.2.tar.gz

Built distribution (wheel)

Table of built distributions (wheels) for norcaster-langchain 0.1.2
File Interpreter ABI Platform Actions
norcaster_langchain-0.1.2-py3-none-any.whl Python 3 none any Details for norcaster_langchain-0.1.2-py3-none-any.whl

Total release size: 87.0 kB

Release files / norcaster_langchain-0.1.2.tar.gz

Download URL norcaster_langchain-0.1.2.tar.gz
Size 55.0 kB
Tags Source
SHA-256 checksum
How to use checksums
fa1e9a173cb4db25b8db168c5bf2c5501e6922cde25879b0bc9bc25fbed1df2e
BLAKE2b-256 checksum
How to use checksums
28c0dfb1eca0f352dc9a85085bcd3f9ba106c45cee1aca4424d4ac2bac3e0f73
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
No
Uploaded via twine/7.0.0 CPython/3.11.14

Release files / norcaster_langchain-0.1.2-py3-none-any.whl

Download URL norcaster_langchain-0.1.2-py3-none-any.whl
Size 32.0 kB
Tags Python 3
SHA-256 checksum
How to use checksums
371912be9bae0ae2f0a7c5df5e24239b203f6c67e145438438db18fabef1ea24
BLAKE2b-256 checksum
How to use checksums
63a3c65d4d05a8d0e8033a615b092665846b0393250ba83c63b70938f7a1134b
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
No
Uploaded via twine/7.0.0 CPython/3.11.14

Security for norcaster-langchain 0.1.2

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.

No provenance found

None of the files in this release were uploaded with provenance metadata.

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.2 This release

2 release files No 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