Skip to main content

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 reads ALICE_TOOL_MESSAGE_TYPES=true) only once Alice has enabled WONDER_FENCE_AGENTIC_MESSAGE_TYPES on 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, and agent.invoke raises 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.