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.
-
Install the adapter into the Python environment that runs your agent. It brings the Norcaster SDK (
norcaster) with it:pip install norcaster-langchain
-
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>")], )
-
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_bodyormodel_kwargschosen 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.
What is refused. A call that holds anything a check can't read is not sent: an image, a file,
audio, 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. An agent that
takes images can't use this adapter yet.
The same goes for a model whose settings carry content of their own:
messages,input,instructionsorpromptinextra_body(on the model, on a bound model, or in a middleware'smodel_settings);instructionsor a storedpromptset on the model;- a predicted output (
prediction, OpenAI's Predicted Outputs) inmodel_kwargs, inextra_body, on a bound model or in a middleware'smodel_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 taggednostream, 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:
- A warning in your app's log (logger
norcaster.check), with the call's id and its SHA-256. - Your
on_uncheckedfunction is called with it. - On the model's answer:
response_metadata["norcaster"]says"decision": "unchecked"and carries the id. - 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 on127.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.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 |
|---|---|---|---|---|
| norcaster_langchain-0.1.1.tar.gz | 52.2 kB | Without provenance | Details for norcaster_langchain-0.1.1.tar.gz |
Built distribution (wheel)
| File | Interpreter | ABI | Platform | Actions Reset |
|---|---|---|---|---|
| norcaster_langchain-0.1.1-py3-none-any.whl | Python 3 | none | any | Details for norcaster_langchain-0.1.1-py3-none-any.whl |
Total release size: 82.3 kB
Release files / norcaster_langchain-0.1.1.tar.gz
| Download URL | norcaster_langchain-0.1.1.tar.gz |
|---|---|
| Size | 52.2 kB |
| Tags | Source |
|
SHA-256 checksum How to use checksums |
379d9b878fba6907c469cc6db4282b2bf46c7d7e9e96d4e21159f535b1a2d5ec
|
|
BLAKE2b-256 checksum How to use checksums |
70519789e1050608ef92563b7e82a710a854d4340077e93344daf6337448319d
|
| 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.1-py3-none-any.whl
| Download URL | norcaster_langchain-0.1.1-py3-none-any.whl |
|---|---|
| Size | 30.1 kB |
| Tags | Python 3 |
|
SHA-256 checksum How to use checksums |
607679510e5cce4c64c9aff7253b8ffb16f22ef4d379018ab8ffb4dba6a61835
|
|
BLAKE2b-256 checksum How to use checksums |
96e4a54c768e450a67c95d76d188714bc9ea86f381fd506c4fbbaaa97c1fce22
|
| 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.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.
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.