feat(integration): add GuardrailsMiddleware for LangChain agent

[Pouyanpi]

#‪# Description

Add a new GuardrailsMiddleware class for seamless integration with LangChain's Agent Middleware system. The middleware intercepts agent conversations to apply NeMo Guardrails input/output validation before and after model calls.

This follows the LangChain Middleware pattern introduced in LangChain 1.0, providing before_model and after_model hooks for precise control over the agent loop.

Key features:

• GuardrailsMiddleware - Full middleware with both input and output rails
• InputRailsMiddleware - Input-only validation
• OutputRailsMiddleware - Output-only validation
• GuardrailViolation exception for programmatic error handling
• Configurable blocking behavior (raise exception vs return blocked message)
• Support for both config_path and config_yaml initialization

Usage example:

from langchain.agents import create_agent
from nemoguardrails.integrations.langchain.middleware import GuardrailsMiddleware

guardrails = GuardrailsMiddleware(
    config_path="./config",
    raise_on_violation=False,
)

agent = create_agent("openai:gpt-4o", middleware=[guardrails])

References

• LangChain Middleware Overview
• LangChain Middleware Reference
• LangChain Agent Middleware Blog Post

[codecov]

Codecov Report

❌ Patch coverage is 89.61039% with 16 lines in your changes missing coverage. Please review.

Files with missing lines	Patch %	Lines
...emoguardrails/integrations/langchain/middleware.py	88.23%	16 Missing ⚠️

📢 Thoughts on this report? Let us know!

[greptile-apps]

Greptile Overview

Greptile Summary

This PR adds a new GuardrailsMiddleware class for seamless integration with LangChain's Agent Middleware system, enabling NeMo Guardrails input/output validation in the agent loop.

Major Changes:

• Introduced GuardrailsMiddleware base class with configurable input/output rails
• Added InputRailsMiddleware and OutputRailsMiddleware specialized classes
• Created GuardrailViolation exception for programmatic error handling
• Implemented both async (abefore_model, aafter_model) and sync (before_model, after_model) hooks
• Added comprehensive unit tests (1195 lines) and E2E tests (551 lines)
• Updated dependencies to support LangChain agent middleware integration

Implementation Quality:

• Well-structured code following separation of concerns
• Proper error handling with fallback mechanisms
• Extensive test coverage including security scenarios
• Clean integration with existing message_utils utilities

Issue Found:

• Method naming inconsistency in OutputRailsMiddleware.before_agent (line 260) - should be before_model to match the parent class signature

Confidence Score: 4/5

• Safe to merge after fixing the method naming issue in OutputRailsMiddleware
• The implementation is well-designed with comprehensive tests, but there's a method naming inconsistency that could cause issues at runtime
• nemoguardrails/integrations/langchain/middleware.py - fix method name on line 260

Important Files Changed

Filename	Overview
nemoguardrails/integrations/langchain/exceptions.py	New exception class for guardrail violations, simple and well-structured
nemoguardrails/integrations/langchain/middleware.py	New middleware implementation with input/output rails integration - has one naming inconsistency issue
tests/integrations/langchain/test_middleware.py	Comprehensive unit tests with mocks covering all middleware scenarios
tests/integrations/langchain/test_middleware_e2e.py	E2E tests with real guardrails configuration, thorough security scenario coverage

Sequence Diagram

sequenceDiagram
    participant User
    participant Agent as LangChain Agent
    participant GM as GuardrailsMiddleware
    participant Rails as LLMRails
    participant Model as LLM

    User->>Agent: Send message
    Agent->>GM: before_model(state, runtime)
    GM->>GM: Check enable_input_rails
    GM->>GM: Check _has_input_rails()
    GM->>GM: Convert messages to dicts
    GM->>Rails: check_async(messages)
    Rails-->>GM: RailsResult (PASSED/BLOCKED)
    
    alt Input Blocked
        GM->>GM: _handle_guardrail_failure()
        alt raise_on_violation=True
            GM-->>Agent: Raise GuardrailViolation
        else raise_on_violation=False
            GM->>GM: Create blocked AI message
            GM-->>Agent: Return {messages, jump_to: "end"}
        end
    else Input Passed
        GM-->>Agent: Return None (continue)
        Agent->>Model: Call LLM
        Model-->>Agent: Generate response
        Agent->>GM: after_model(state, runtime)
        GM->>GM: Check enable_output_rails
        GM->>GM: Check _has_output_rails()
        GM->>GM: Get last AI message
        GM->>GM: Convert messages to dicts
        GM->>Rails: check_async(messages)
        Rails-->>GM: RailsResult (PASSED/BLOCKED)
        
        alt Output Blocked
            GM->>GM: _handle_guardrail_failure()
            alt raise_on_violation=True
                GM-->>Agent: Raise GuardrailViolation
            else raise_on_violation=False
                GM->>GM: Replace last message with blocked message
                GM-->>Agent: Return {messages: modified}
            end
        else Output Passed
            GM-->>Agent: Return None (continue)
            Agent-->>User: Return response
        end
    end

Loading

[greptile-apps]

_{4 files reviewed, 1 comment}

_{Edit Code Review Agent Settings | Greptile}

[tgasser-nv]

Can you run a local integration test to make sure this works ?

[Pouyanpi]

@tgasser-nv I've done proper e2e tests and verifications. Will share them with QA 👍🏻

[tgasser-nv]

Looks good, thanks for updating the Runtime argument. Can you make sure QA have good coverage on these methods for integration testing?