langchain-cisco-aidefense

LangChain agent middleware for Cisco AI Defense, providing runtime security inspection of LLM inputs/outputs and tool/MCP calls.

Detects prompt injection, jailbreaks, PII leakage, toxic content, and unsafe tool usage — directly within the LangChain agent loop.

Installation

pip install langchain-cisco-aidefense

Middleware Overview

create_agent (LangChain LCEL) — four middleware classes

LLM Inspection (before_model / after_model)

Tool / MCP Inspection (wrap_tool_call)

create_react_agent (LangGraph prebuilt) — added in v1.1.0

Quick Start

pip install langchain-cisco-aidefense langchain-openai

from aidefense_langchain import AIDefenseMiddleware
from langchain.agents import create_agent

agent = create_agent(
    model="openai:gpt-4.1",
    tools=[get_weather],
    middleware=[
        AIDefenseMiddleware(
            api_key="your-cisco-ai-defense-api-key",
            region="us-west-2",
            mode="enforce",
        ),
    ],
)

result = agent.invoke({"messages": [{"role": "user", "content": "Hello!"}]})

LLM Inspection

AIDefenseMiddleware (Recommended)

Uses ChatInspectionClient directly. Self-contained configuration, no global state, no monkey-patching.

from aidefense_langchain import AIDefenseMiddleware
from langchain.agents import create_agent

agent = create_agent(
    model="openai:gpt-4.1",
    tools=[get_weather],
    middleware=[
        AIDefenseMiddleware(
            api_key="your-api-key",
            region="us-west-2",
            mode="enforce",       # "enforce" | "monitor" | "off"
            fail_open=True,
        ),
    ],
)

Parameters

How it works

User message
    |
    v
+--------------------------------------------------+
|  before_model hook                               |
|  -> ChatInspectionClient.inspect_conversation()  |
|  -> if not safe and mode="enforce": jump_to=end  |
+--------------------------------------------------+
    |
    v
  LLM call
    |
    v
+--------------------------------------------------+
|  after_model hook                                |
|  -> ChatInspectionClient.inspect_conversation()  |
|  -> if not safe and mode="enforce": jump_to=end  |
+--------------------------------------------------+
    |
    v
Agent response

AIDefenseAgentsecMiddleware

Uses agentsec's LLMInspector — gets retry with exponential backoff and fail-open semantics.

from aidefense_langchain import AIDefenseAgentsecMiddleware
from langchain.agents import create_agent

agent = create_agent(
    model="openai:gpt-4.1",
    tools=[get_weather],
    middleware=[
        AIDefenseAgentsecMiddleware(
            mode="enforce",
            api_key="your-api-key",
            endpoint="https://us.api.inspect.aidefense.security.cisco.com",
            retry_total=3,
            retry_backoff=1.0,
        ),
    ],
)

Do not call agentsec.protect() when using middleware. The middleware handles all inspection directly. Calling protect() would activate monkey-patching on the underlying LLM SDK, causing every request to be inspected twice — once by the patched SDK and once by the middleware — doubling latency and API calls with no security benefit.

Parameters

Tool / MCP Inspection

AIDefenseToolMiddleware (Recommended for tools)

Uses MCPInspectionClient to inspect tool call requests (name + arguments) and tool call results.

from aidefense_langchain import AIDefenseMiddleware, AIDefenseToolMiddleware
from langchain.agents import create_agent

agent = create_agent(
    model="openai:gpt-4.1",
    tools=[search_db, send_email],
    middleware=[
        AIDefenseMiddleware(api_key="your-key", mode="enforce"),
        AIDefenseToolMiddleware(api_key="your-key", mode="enforce"),
    ],
)

AIDefenseAgentsecToolMiddleware

Uses agentsec's MCPInspector with retry, backoff, and fail-open support.

from aidefense_langchain import AIDefenseAgentsecMiddleware, AIDefenseAgentsecToolMiddleware

agent = create_agent(
    model="openai:gpt-4.1",
    tools=[read_file, execute_query],
    middleware=[
        AIDefenseAgentsecMiddleware(mode="enforce", api_key="your-key"),
        AIDefenseAgentsecToolMiddleware(mode="enforce", api_key="your-key"),
    ],
)

Tool Middleware Parameters

How tool inspection works

Tool call (from LLM)
    |
    v
+--------------------------------------------------+
|  wrap_tool_call -- PRE-CALL inspection           |
|  -> MCPInspectionClient.inspect_tool_call()      |
|  -> if not safe and mode="enforce": return block |
+--------------------------------------------------+
    |
    v
  Tool executes
    |
    v
+--------------------------------------------------+
|  wrap_tool_call -- POST-CALL inspection          |
|  -> MCPInspectionClient.inspect_response()       |
|  -> if not safe and mode="enforce": return block |
+--------------------------------------------------+
    |
    v
Tool result returned to agent

This covers all tool types:

• LangChain tools (@tool decorated functions)
• MCP tools registered via LangChain's MCP integration
• Any tool executed through the agent's tool node

Environment Variables

The middleware can also be configured via environment variables (used by from_env() class methods):

export AIDEFENSE_API_KEY=your-api-key
export AIDEFENSE_REGION=us-west-2
export AIDEFENSE_MODE=enforce
export AIDEFENSE_FAIL_OPEN=true
export AIDEFENSE_TIMEOUT=30

from aidefense_langchain import AIDefenseMiddleware

middleware = AIDefenseMiddleware.from_env()

Comparison

Recommendation: Use AIDefenseMiddleware for new projects. Use AIDefenseAgentsecMiddleware when you need agentsec's retry/backoff machinery.

Enforcement Modes

Fail-Open Behavior

When fail_open=True (default) and the AI Defense inspection API is unreachable:

• The request is allowed to proceed
• A warning is logged

When fail_open=False:

• The request is blocked (or an exception is raised)

Examples

create_react_agent Integration (v1.1.0)

LangGraph's create_react_agent does not expose before_model / after_model hooks, so the middleware classes above cannot be used with it directly. v1.1.0 adds native support via LangGraph's pre_model_hook, post_model_hook, and ToolNode.wrap_tool_call.

Requires langgraph >= 0.2.27.

Option A — Primitives (maximum control)

from langchain_openai import ChatOpenAI
from langchain_core.tools import tool
from langgraph.prebuilt import create_react_agent
from aidefense_langchain import AIDefenseHooks, AIDefenseToolNode, AIDefenseViolationError

@tool
def get_weather(city: str) -> str:
    """Return current weather for a city."""
    return f"It's 72°F and sunny in {city}!"

hooks = AIDefenseHooks(api_key="<AIDEFENSE_API_KEY>", mode="enforce")
tool_node = AIDefenseToolNode([get_weather], api_key="<AIDEFENSE_API_KEY>", mode="enforce")

agent = create_react_agent(
    model=ChatOpenAI(model="gpt-4o-mini"),
    tools=tool_node,
    pre_model_hook=hooks.pre_model_hook,
    post_model_hook=hooks.post_model_hook,
)

try:
    result = agent.invoke({"messages": [("user", "What's the weather in Seattle?")]})
    print(result["messages"][-1].content)
except AIDefenseViolationError as e:
    print(f"Blocked at '{e.direction}': {e}")

Option B — Convenience wrapper (minimum changes)

from aidefense_langchain import create_aidefense_react_agent, AIDefenseViolationError

agent = create_aidefense_react_agent(
    model=ChatOpenAI(model="gpt-4o-mini"),
    tools=[get_weather],
    api_key="<AIDEFENSE_API_KEY>",
    mode="enforce",
)

Violation handling

AIDefenseViolationError carries:

• .direction — "input", "output", "tool '<name>' input", or "tool '<name>' output"
• .response — the full InspectResponse from the SDK (includes event_id, severity, explanation)

In "monitor" mode, violations are logged and the optional on_violation callback is invoked, but the agent continues:

violations = []
agent = create_aidefense_react_agent(
    model=llm, tools=[get_weather],
    api_key="<AIDEFENSE_API_KEY>",
    mode="monitor",
    on_violation=lambda resp, direction: violations.append(direction),
)

LangGraph V2.0 note: create_react_agent is deprecated in langgraph.prebuilt (LangGraph V1.0) and will move to langchain.agents in V2.0. Update your import when you upgrade.

Development

git clone https://github.com/cisco-ai-defense/ai-defense-langchain-middleware.git
cd ai-defense-langchain-middleware
pip install -e ".[dev,examples]"
pytest

License

Apache-2.0 — see LICENSE for details.