sentraguard-agent 0.1.0

SentraGuard framework-neutral guardrail core for AI agents — LangChain/LangGraph, LiteLLM, and direct provider adapters (no OpenTelemetry dependency).

sentraguard-agent

Framework-neutral SentraGuard guardrail core for AI agents — LangChain/LangGraph, LiteLLM, and direct provider adapters. No OpenTelemetry dependency.

sentraguard-agent adds capture, identity attribution, and inline policy enforcement to AI-agent code with minimal change. The core (policy engine, identity, decisions, threats mapping) is framework-neutral; framework adapters are namespaced:

Import	Covers
sentraguard_agent	the framework-neutral core (engine, identity, threats)
sentraguard_agent.langchain	LangChain / LangGraph hooks (callbacks, middleware, wrappers)
sentraguard_agent.litellm	LiteLLM CustomGuardrail + CustomLogger (enforce under the Proxy; capture under SDK + Proxy)
sentraguard_agent.openai_agents	OpenAI Agents SDK input/output guardrails + run hooks
sentraguard_agent.google_adk	Google ADK (Gemini) runner plugin (before_model/tool callbacks)
sentraguard_agent.crewai	CrewAI task guardrail + tool hook + event listener
sentraguard_agent.providers	direct OpenAI / Anthropic / Gemini drop-ins

It uses the published sentraguard-sdk distribution (import name sentraguard) internally as its client (transport, auth, retries) — no new endpoints, no collector, no OTel.

Complete guide: docs/SENTRAGUARD_AGENT_SDK_GUIDE.md. Live in-framework test evidence: tests/integration/ — verified against openai-agents 0.17.4, litellm 1.88.0, google-adk 2.2.0, crewai 1.14.6.

Install

pip install "sentraguard-agent[langchain]"            # LangChain / LangGraph
pip install "sentraguard-agent[litellm]"              # LiteLLM (SDK or Proxy)
pip install "sentraguard-agent[langchain,openai]"     # + guard DIRECT (non-framework) OpenAI calls
pip install "sentraguard-agent[memory]"               # + Agent Memory Guard composition

The sentraguard-sdk distribution is a core dependency. LangChain/LangGraph, LiteLLM, Agent Memory Guard, and the provider drop-ins are optional extras. The pure policy engine still imports without the frameworks for embedding/testing.

Covering every surface

Call path	Guarded by
LangChain / LangGraph framework calls	sentraguard_agent.langchain (capture + middleware + wrappers)
LiteLLM (SDK or Proxy)	sentraguard_agent.litellm (guardrail + logger)
Direct openai/anthropic/gemini calls outside a framework	sentraguard_agent.providers.*

1. LangChain — zero-code-change capture (SAIS-327)

One import at startup; the handler auto-attaches to every run via register_configure_hook. No edits to your invoke/stream call sites.

# bootstrap_sentraguard.py
import sentraguard_agent.langchain.bootstrap as sg
from sentraguard_agent import BatchingAnalyticsSink, sdk_forwarder
from sentraguard import SentraGuard

client = SentraGuard()                      # internal SDK, auto-config
sg.install(BatchingAnalyticsSink(sdk_forwarder(client)))

# app.py — add ONE import near the top; nothing else changes
import bootstrap_sentraguard   # noqa: F401

2. LangChain — authenticated identity (SAIS-329)

agent.invoke(state, config={"metadata": {"user_id": u.id, "org_id": org.id, "session_id": sid}})

3. LangChain — inline enforcement (SAIS-330)

Prebuilt agent — one line:

from sentraguard_agent import PolicyEngine
from sentraguard_agent.langchain import SentraGuardMiddleware

agent = create_agent(model, tools, middleware=[SentraGuardMiddleware(PolicyEngine())])

Custom StateGraph — wrap, don't rewrite:

from sentraguard_agent import PolicyEngine
from sentraguard_agent.langchain import SentraGuardModelWrapper, guard_tool
eng = PolicyEngine()
model = SentraGuardModelWrapper(model, eng)
tools = [guard_tool(t, eng) for t in tools]

4. LiteLLM — SDK and Proxy

LiteLLM SDK — register the guardrail + logger:

import litellm
from sentraguard_agent.litellm import SentraGuardLiteLLMGuardrail, SentraGuardLiteLLMLogger

litellm.callbacks = [SentraGuardLiteLLMGuardrail(), SentraGuardLiteLLMLogger()]
litellm.completion(model="gpt-4o", messages=[...])   # capture (logger) runs under the SDK

Enforcement scope (verified, litellm 1.88.0): the pre/post-call enforcement hooks fire only under the LiteLLM Proxy. Under the bare SDK only the logger (capture) runs. To enforce on direct (non-proxy) calls, use the provider drop-ins (sentraguard_agent.providers.*) or route via the Proxy.

LiteLLM Proxy (the inline-gateway deployment, where enforcement applies) — reference the guardrail in config.yaml:

guardrails:
  - guardrail_name: sentraguard
    litellm_params:
      guardrail: sentraguard_agent.litellm.SentraGuardLiteLLMGuardrail
      mode: [pre_call, post_call]

A LiteLLM model used inside LangChain (ChatLiteLLM) is already covered by the LangChain hooks — no LiteLLM adapter needed there.

5. Other agent frameworks

OpenAI Agents SDK — input/output guardrails (DENY trips the tripwire, halting the run) + run hooks for capture:

from agents import Agent
from sentraguard_agent.openai_agents import SentraGuardAgentsGuardrail, SentraGuardRunHooks
g = SentraGuardAgentsGuardrail()
agent = Agent(name="...", input_guardrails=[g.as_input_guardrail()],
              output_guardrails=[g.as_output_guardrail()])

Google ADK (Gemini) — a runner-level plugin (blocks at before_model_callback, gates tools):

from google.adk.runners import Runner
from sentraguard_agent.google_adk import SentraGuardADKPlugin
runner = Runner(agent=..., plugins=[SentraGuardADKPlugin()])

CrewAI — task guardrail + tool hook (enforcement is at the tool/task gate):

from sentraguard_agent.crewai import SentraGuardCrewAI
sg = SentraGuardCrewAI()
task = Task(..., guardrail=sg.task_guardrail)   # + register sg.before_tool_hook as a BeforeToolCallHook

Roadmap (Tier 2+): Microsoft Agent Framework, LlamaIndex, Pydantic AI, AWS Strands — see the roadmap section of docs/SENTRAGUARD_AGENT_SDK_GUIDE.md.

6. Direct provider calls

from sentraguard_agent.providers.openai import OpenAI   # was: from openai import OpenAI
client = OpenAI()                                        # auto-guarded

7. Coverage modules (framework-neutral)

• MCP security (SAIS-332): sentraguard_agent.mcp — scan_tools, ToolPinRegistry.
• Memory integrity (SAIS-333): sentraguard_agent.memory.MemoryGuard (composes Agent Memory Guard).
• Behavioural features (SAIS-331): sentraguard_agent.analytics_features — extract_features, score (incl. multi-agent).
• Threat mapping (SAIS-334): map_detection, coverage_matrix, export_coverage_markdown (OWASP + MITRE ATLAS).

License

MIT © Sovereign AI Security Labs