LangChain
A LangChain AgentMiddleware subclass. wrap_model_call evaluates the latest human message before the model and the AI message it returns after; wrap_tool_call evaluates tool arguments before execution and the tool output after, as a prompt and a response or, with tool_message_types, as a tool call and a tool result. Block raises, mask rewrites the message content.
Status: Generally available ยท Evaluates: Prompts, Responses, Tool calls ยท Vendor: LangChain
Prompt, response, tool input, tool output. Session and user ids come from agent state.
Setupโ
pip install "langchain>=1.0" "langgraph>=1.0" "wonderfence-sdk>=3.1.0"
Configuration: ALICE_API_KEY, ALICE_APP_ID
Note: Tool message types are opt-in. Off by default, tool input is screened as a prompt and tool output as a response, which works on every project. Turn on
tool_message_types=True(the example readsALICE_TOOL_MESSAGE_TYPES=true) only once Alice has enabledWONDER_FENCE_AGENTIC_MESSAGE_TYPESon your project and your policies list Tool Call / Tool Result: a policy that lists only Prompt or Response does not screen tool traffic sent under its own message types. Turned on without the flag, the API answers 400 on every tool check, the middleware raises, andagent.invokeraises on every turn where the model calls a tool.
Exampleโ
imports (langchain_hooks_simple.py)
import json
import logging
import os
import uuid
from typing import Any, Optional, Union, cast
from langchain.agents import create_agent
from langchain.agents.middleware import AgentMiddleware, AgentState
from langchain_core.messages import AIMessage, HumanMessage, ToolMessage
from langchain_core.tools import tool
from langchain_google_genai import ChatGoogleGenerativeAI
from langgraph.prebuilt.tool_node import ToolCallRequest
from langgraph.types import Command
from wonderfence_sdk.client import WonderFenceV2Client
from wonderfence_sdk.models import MAX_TOOL_FIELD_LENGTH, Actions, AnalysisContext
middleware: prompt check
class WonderFenceSafetyMiddleware(AgentMiddleware):
"""
Middleware that integrates WonderFence SDK for safety checks.
Hooks into LangChain agent lifecycle to:
- Check prompt safety before model calls (_before_model)
- Check response safety after model calls (_after_model)
- Check tool input safety before tool calls (_before_tool)
- Check tool output safety after tool calls (_after_tool)
"""
def __init__(self, wonderfence_client: WonderFenceV2Client, app_id: str, tool_message_types: bool = False):
"""
Initialize the WonderFence safety middleware.
Args:
wonderfence_client: WonderFenceV2Client client for safety evaluation
app_id: UUID of the WonderFence application whose policies to apply
tool_message_types: False (default) evaluates tool input as a prompt and tool output
as a response. True sends them as tool_call / tool_result with the tool name and
call id; it needs WONDER_FENCE_AGENTIC_MESSAGE_TYPES on the project and policies
that list Tool Call / Tool Result.
"""
super().__init__()
self.client = wonderfence_client
self.app_id = app_id
self.tool_message_types = tool_message_types
def _generate_wonderfence_context_from_state(self, state: AgentState) -> AnalysisContext:
"""
Generate an analysis context from the agent state.
"""
return AnalysisContext(
session_id=state.get("session_id", str(uuid.uuid4())),
user_id=state.get("user_id", "anonymous"),
)
def _before_model(self, state: AgentState) -> None:
"""Check prompt safety before model execution."""
logger.info("๐ Checking prompt safety with WonderFence...")
messages = state.get("messages", [])
if not messages:
return
# Find the latest user message
user_messages = [msg for msg in messages if isinstance(msg, HumanMessage)]
if not user_messages:
return
latest_message = user_messages[-1]
if not hasattr(latest_message, "content"):
return
content = getattr(latest_message, "content", None)
if content is None:
return
content_str = str(content).strip()
if not content_str:
return
analysis_context = self._generate_wonderfence_context_from_state(state)
try:
logger.info(f" ๐ Evaluating prompt safety ({len(content_str)} chars)")
evaluation = self.client.evaluate_prompt_sync(self.app_id, analysis_context, content_str)
logger.info(f" โ
Prompt safety check: {evaluation.action.name}")
if evaluation.action == Actions.BLOCK:
raise Exception(f"Prompt blocked: {getattr(evaluation, 'explanation', 'Safety violation')}")
if evaluation.action == Actions.MASK:
if hasattr(latest_message, "content") and evaluation.action_text:
latest_message.content = evaluation.action_text # type: ignore[attr-defined]
logger.info(" ๐ญ MASKED: Content modified for safety")
except Exception as e:
logger.error(f" โ Prompt safety check failed: {e}", exc_info=True, stack_info=True)
raise
middleware: wrap_model_call
def wrap_model_call(
self,
request: Any,
handler: Any,
) -> Any:
"""
Wrap model call with prompt and response safety checks.
This method replaces before_model and after_model hooks, providing
a single point of control for the entire model call lifecycle.
Args:
request: Model request object containing state and other information
handler: Handler function that executes the actual model call
Returns:
The model response, potentially modified by safety checks
"""
# Extract state from request (similar to wrap_tool_call pattern)
# Request may be the state dict directly, or an object with a state attribute
if isinstance(request, dict):
state = cast(AgentState, request)
elif hasattr(request, "state"):
state = cast(AgentState, request.state)
else:
state = cast(AgentState, {})
# Before model call - check prompt safety
self._before_model(state)
# Execute the model call
result = handler(request)
# After model call - check response safety. The handler returns a ModelResponse whose
# `result` holds the new AIMessage; the request state does not contain it yet.
new_messages = getattr(result, "result", None)
if isinstance(new_messages, list):
self._after_model(cast(AgentState, {**state, "messages": new_messages}))
return result
middleware: tool call and tool result checks + wrap_tool_call
def _before_tool(
self, tool_name: Optional[str], tool_call_id: Optional[str], tool_input: dict[str, Any], state: AgentState
) -> dict[str, Any]:
"""Check tool input safety before tool execution."""
logger.info(f"๐ Checking tool '{tool_name}' input safety with WonderFence...")
# JSON, so a masked verdict's action_text parses back into arguments
content_str = json.dumps(tool_input, ensure_ascii=False, default=str)
analysis_context = self._generate_wonderfence_context_from_state(state)
try:
if self.tool_message_types:
evaluation = self.client.evaluate_tool_call_sync(
self.app_id,
analysis_context,
content_str,
tool_name=_valid_tool_field(tool_name),
tool_call_id=_valid_tool_field(tool_call_id),
)
else:
evaluation = self.client.evaluate_prompt_sync(self.app_id, analysis_context, content_str)
logger.info(f" โ
Tool input safety check: {evaluation.action.name}")
if evaluation.action == Actions.BLOCK:
raise Exception(f"Tool call blocked: {getattr(evaluation, 'explanation', 'Safety violation')}")
elif evaluation.action == Actions.MASK:
masked_input = _parse_masked_args(evaluation.action_text)
if masked_input is None:
# Passing the original arguments on would leak what WonderFence asked to redact
raise Exception(f"Tool call blocked: masked arguments for '{tool_name}' are not a JSON object")
logger.info(" ๐ญ MASKED: Tool input modified for safety")
return masked_input
return tool_input
except Exception as e:
logger.error(f" โ Tool safety check failed: {e}", exc_info=True, stack_info=True)
raise e
def _after_tool(
self, tool_name: Optional[str], tool_call_id: Optional[str], tool_result: str, state: AgentState
) -> str:
"""Check tool output safety after tool execution; return the text the agent may read."""
logger.info(f"๐ Checking tool '{tool_name}' output safety with WonderFence...")
content_str = str(tool_result).strip()
if not content_str:
return tool_result
analysis_context = self._generate_wonderfence_context_from_state(state)
try:
if self.tool_message_types:
evaluation = self.client.evaluate_tool_result_sync(
self.app_id,
analysis_context,
content_str,
tool_name=_valid_tool_field(tool_name),
tool_call_id=_valid_tool_field(tool_call_id),
)
else:
evaluation = self.client.evaluate_response_sync(self.app_id, analysis_context, content_str)
logger.info(f" โ
Tool output safety check: {evaluation.action.value}")
if evaluation.action == Actions.BLOCK:
raise Exception(f"Tool output blocked: {evaluation.detections}")
if evaluation.action == Actions.MASK:
if not evaluation.action_text:
# Passing the output on would leak what WonderFence asked to redact
raise Exception(f"Tool output blocked: no masked text returned for '{tool_name}'")
logger.info(" ๐ญ MASKED: Tool output modified for safety")
return evaluation.action_text
return tool_result
except Exception as e:
logger.error(f" โ Tool output safety check failed: {e}")
raise
def wrap_tool_call(
self,
request: ToolCallRequest,
handler: Any,
) -> Union[ToolMessage, Command]:
"""Wrap tool execution with before/after safety checks."""
tool_name = request.tool_call.get("name") or None
tool_call_id = request.tool_call.get("id") or None
tool_input = request.tool_call.get("args", {})
# Before tool check
modified_tool_input = self._before_tool(tool_name, tool_call_id, tool_input, request.state)
request.tool_call.update({"args": modified_tool_input})
# Execute tool
result = handler(request)
# After tool check: the agent reads the masked output when WonderFence masks it
if isinstance(result, ToolMessage):
# List content is evaluated (and, on MASK, replaced) as its string form
content = result.content if isinstance(result.content, str) else str(result.content)
safe_content = self._after_tool(tool_name, tool_call_id, content, request.state)
if safe_content is not content:
result = result.model_copy(update={"content": safe_content})
return cast(Union[ToolMessage, Command], result)
def _valid_tool_field(value: Any) -> Optional[str]:
"""value if the API accepts it as tool_name / tool_call_id (1-255 UTF-16 units after trimming), else None.
Optional metadata: an unusable value is dropped rather than failing the evaluation.
"""
if not isinstance(value, str):
return None
stripped = value.strip()
if not stripped or len(stripped.encode("utf-16-le")) // 2 > MAX_TOOL_FIELD_LENGTH:
return None
return value
def _parse_masked_args(action_text: Optional[str]) -> Optional[dict[str, Any]]:
"""The redacted tool arguments, or None when the masked text is no longer a JSON object."""
try:
args = json.loads(action_text or "")
except ValueError:
return None
return args if isinstance(args, dict) else None
wiring
def main() -> None:
"""
Main demo function showing WonderFence integration with LangChain agent.
"""
# Step 1: Initialize WonderFenceV2Client client (reads ALICE_API_KEY)
client = WonderFenceV2Client()
# Step 2: Create middleware with WonderFence client and application id.
# tool_message_types=True once the project has WONDER_FENCE_AGENTIC_MESSAGE_TYPES.
safety_middleware = WonderFenceSafetyMiddleware(
client,
app_id=os.environ["ALICE_APP_ID"],
tool_message_types=os.environ.get("ALICE_TOOL_MESSAGE_TYPES") == "true",
)
# Step 3: Create LangChain model
model = ChatGoogleGenerativeAI(
model="gemini-2.5-flash"
)
# Step 4: Create agent with middleware
agent = create_agent(
model=model,
tools=[calculator],
middleware=[safety_middleware] # register the middleware with the agent
)
Good to knowโ
Pass session_id and user_id in invoke() so every verdict is traceable in the Alice dashboard. The excerpts above leave out _after_model, which the full langchain_hooks_simple.py defines: it mirrors the prompt check with evaluate_response_sync, raises on BLOCK, and on MASK rewrites the AI message's content in place, so the agent reads the masked answer. Text over 10,240 characters gets a 400, which the middleware raises, so a turn with an oversized tool input or output fails rather than passing unscreened.