UnplugAI · chiruu12 · Jun 25, 2026 · Jun 25, 2026 · Jun 25, 2026 · Jun 25, 2026
diff --git a/.github/workflows/integrations-live.yml b/.github/workflows/integrations-live.yml
@@ -0,0 +1,79 @@
+name: Integrations (live)
+
+# Live agent-framework coverage. Each matrix leg installs ONE framework extra in an
+# isolated env and runs that framework's live test, so a single SDK's dependency tree
+# can't mask or break another. Kept off the default PR gate (the core CI matrix no
+# longer installs agent frameworks — see `all` extra in pyproject.toml); runs on PRs
+# that touch the integration surface, nightly, and on demand.
+
+on:
+ pull_request:
+ branches: [dev]
-branches: [dev]
+branches: [dev, main]
-branches: [dev]
+branches: [dev, main]
+ paths:
+ - "sdk/src/unplug/integrations/**"
+ - "sdk/tests/optional/live/**"
+ - "sdk/pyproject.toml"
+ - ".github/workflows/integrations-live.yml"
+ schedule:
+ - cron: "0 6 * * *"
+ workflow_dispatch:
+
+permissions:
+ contents: read
+
+jobs:
+ live:
+ runs-on: ubuntu-latest
+ strategy:
+ fail-fast: false
+ matrix:
+ include:
+ - extra: langgraph
+ test: tests/optional/live/test_langgraph_live.py
+ - extra: agno
+ test: tests/optional/live/test_agno_live.py
+ - extra: crewai
+ test: tests/optional/live/test_crewai_live.py
+ - extra: autogen
+ test: tests/optional/live/test_autogen_live.py
+ - extra: llama-index
+ test: tests/optional/live/test_llama_index_live.py
+ - extra: pydantic-ai
+ test: tests/optional/live/test_pydantic_ai_live.py
+ - extra: semantic-kernel
+ test: tests/optional/live/test_semantic_kernel_live.py
+ name: live (${{ matrix.extra }})
+ defaults:
+ run:
+ working-directory: sdk
+ steps:
+ - uses: actions/checkout@df4cb1c069e1874edd31b4311f1884172cec0e10 # v6
+
+ - uses: astral-sh/setup-uv@fac544c07dec837d0ccb6301d7b5580bf5edae39 # v8.2.0
+ with:
+ enable-cache: true
+ version: "0.6.14"
+
+ - uses: actions/setup-python@a309ff8b426b58ec0e2a45f0f869d46889d02405 # v6
+ with:
+ python-version: "3.12"
+
+ - name: Install (one framework extra in isolation)
+ run: uv sync --extra dev --extra ${{ matrix.extra }}
+
+ - name: Live integration test
+ run: |
+ set +e
+ uv run pytest -q -m requires_integrations ${{ matrix.test }}
+ rc=$?
+ set -e
+ # Exit 5 = pytest collected nothing because the module self-skipped:
+ # the framework installed but is unimportable under our pinned deps
+ # (e.g. an upstream release incompatible with our Pydantic v2). That is
+ # an upstream conflict, not an Unplug regression — surface it loudly but
+ # don't block. Real test failures (exit 1) still fail the job.
+ if [ "$rc" -eq 5 ]; then
+ echo "::warning title=Live integration skipped::${{ matrix.extra }} installed but its live tests were skipped (framework unimportable under current deps). Tolerated; not blocking."
+ exit 0
+ fi
-if [ "$rc" -eq 5 ]; then
-echo "::warning title=Live integration skipped::${{ matrix.extra }} installed but its live tests were skipped (framework unimportable under current deps). Tolerated; not blocking."
-exit 0
-fi
+if [ "$rc" -eq 5 ]; then
+if [ ! -f "${{ matrix.test }}" ]; then
+echo "::error title=Live integration test missing::${{ matrix.test }} does not exist"
+exit 1
+fi
+echo "::warning title=Live integration skipped::${{ matrix.extra }} installed but its live tests were skipped (framework unimportable under current deps). Tolerated; not blocking."
+exit 0
+fi
-if [ "$rc" -eq 5 ]; then
-echo "::warning title=Live integration skipped::${{ matrix.extra }} installed but its live tests were skipped (framework unimportable under current deps). Tolerated; not blocking."
-exit 0
-fi
+if [ "$rc" -eq 5 ]; then
+if [ ! -f "${{ matrix.test }}" ]; then
+echo "::error title=Live integration test missing::${{ matrix.test }} does not exist"
+exit 1
+fi
+echo "::warning title=Live integration skipped::${{ matrix.extra }} installed but its live tests were skipped (framework unimportable under current deps). Tolerated; not blocking."
+exit 0
+fi
+ exit $rc
diff --git a/CHANGELOG.md b/CHANGELOG.md
@@ -4,6 +4,20 @@ All notable changes to the `unplug-ai` SDK.
 
 ## [Unreleased]
 
+## [0.4.1] — 2026-06-25
+
+### Added
+
+- Agent-framework integration hub (`unplug.integrations.*`): framework-agnostic `AgentHooks` plus adapters for LangGraph, Agno, CrewAI, AutoGen, LlamaIndex, Pydantic AI, Semantic Kernel, and a custom-loop guide
+- Per-framework optional extras (`unplug-ai[langgraph]`, `[agno]`, `[crewai]`, `[autogen]`, `[llama-index]`, `[pydantic-ai]`, `[semantic-kernel]`, `[mcp]`) and an `integrations` meta-extra that installs them all
+- 40-angle agent security matrix (`tests/security/test_agent_integration_matrix.py`)
+- Live per-framework integration tests (`tests/optional/live/`) behind a dedicated `Integrations (live)` CI job (per-framework matrix, `requires_integrations` marker), with exit-5 tolerance for frameworks that are unimportable under our pinned deps
+- Integrations documentation hub under `integrations/` (per-framework guides + `TESTING.md`)
+
+### Changed
+
+- `all` extra now installs capability extras only (`ml,scrape,litellm,yara,haystack,presidio`); agent-framework adapters install via the `integrations` extra (or one at a time) so the core dependency tree and default CI matrix stay lean
+
 ## [0.4.0] — 2026-06-24
 
 ### Added

diff --git a/sdk/README.md b/sdk/README.md
@@ -215,7 +215,7 @@ Copy `unplug.example.toml` to `unplug.toml` to customize scanners, tool profiles
 
 ## Integrations
 
-Framework hooks for LangGraph and Agno, plus framework-agnostic patterns: [`docs/INTEGRATIONS.md`](docs/INTEGRATIONS.md).
+Framework hooks for LangGraph, CrewAI, AutoGen, Haystack, and more: [`integrations/README.md`](integrations/README.md) (guides) · [`docs/INTEGRATIONS.md`](docs/INTEGRATIONS.md) (API reference).
 
 Threat scanners live under `unplug.scanners` (canonical). The older `unplug.safeguards` path still works but emits deprecation warnings:
 
@@ -243,7 +243,8 @@ See [docs/ARCHITECTURE.md](docs/ARCHITECTURE.md) for layering and optional extra
 | [`docs/DEPLOYMENT.md`](docs/DEPLOYMENT.md) | Hosted vs embedded vs sidecar architecture |
 | [`docs/BENCHMARKS.md`](docs/BENCHMARKS.md) | Regex vs regex + ML eval results (neuralchemy, microsoft) |
 | [`docs/ML_INTEGRATION.md`](docs/ML_INTEGRATION.md) | Checkpoint layout, thresholds, long-text and streaming config |
-| [`docs/INTEGRATIONS.md`](docs/INTEGRATIONS.md) | LangGraph, Agno, framework-agnostic hooks |
+| [`integrations/README.md`](integrations/README.md) | Per-framework guides, extras, security matrix |
+| [`docs/INTEGRATIONS.md`](docs/INTEGRATIONS.md) | LangGraph, Agno, CrewAI, hooks API |
 | [`docs/AGENT_FLOW_SECURITY.md`](docs/AGENT_FLOW_SECURITY.md) | End-to-end agent hardening flow |
 | [`docs/HERMES_AGENT_SECURITY.md`](docs/HERMES_AGENT_SECURITY.md) | Context-file scanning for agent frameworks |
 

diff --git a/sdk/docs/INTEGRATIONS.md b/sdk/docs/INTEGRATIONS.md
@@ -1,6 +1,15 @@
 # Agent framework integrations
 
-Unplug ships **framework-agnostic hooks** first. LangGraph and Agno do not need to be installed to use the SDK: copy the patterns below or run the demos.
+> **Full guides:** [`integrations/README.md`](../integrations/README.md) — per-framework wiring, extras, and the [40-angle security matrix](../integrations/TESTING.md).
+
+Unplug ships **framework-agnostic hooks** first. Install only the extra for your stack:
+
+```bash
+pip install unplug-ai # core — no agent SDK deps
+pip install "unplug-ai[langgraph]" # LangGraph
+pip install "unplug-ai[crewai]" # CrewAI
+pip install "unplug-ai[integrations]" # all documented agent/RAG extras
+```
 
 ## Core: `AgentHooks`
 
@@ -21,115 +30,68 @@ tool_decision = hooks.before_tool_call("send_email", {"to": "...", "body": "..."
 | Hook | When to call |
 |------|----------------|
 | `scan_user_input` | Before LLM turn |
-| `wrap_retrieved_content` | After RAG / web fetch, before context insert |
-| `before_tool_call` | Before every tool execution (always local, even in server mode) |
-| `scan_agent_output` | Before returning response to user |
-| `scan_request_isolated` | Eval / probes (no session taint bleed) |
+| `wrap_retrieved_content` | After RAG / web fetch |
+| `before_tool_call` | Before every tool (always local) |
+| `scan_agent_output` | Before returning to user |
+| `scan_request_isolated` | Eval / probes (no session bleed) |
+
+## Framework modules
+
+| Framework | Extra | Module |
+|-----------|-------|--------|
+| LangGraph | `langgraph` | `unplug.integrations.langgraph` |
+| Agno | `agno` | `unplug.integrations.agno` |
+| CrewAI | `crewai` | `unplug.integrations.crewai` |
+| AutoGen | `autogen` | `unplug.integrations.autogen` |
+| Haystack | `haystack` | `unplug.integrations.haystack` |
+| LlamaIndex | `llama-index` | `unplug.integrations.llama_index` |
+| Pydantic AI | `pydantic-ai` | `unplug.integrations.pydantic_ai` |
+| Semantic Kernel | `semantic-kernel` | `unplug.integrations.semantic_kernel` |
+| Custom loop | *(none)* | `unplug.integrations.hooks` |
 
 ## LangGraph
 
 ```python
-from unplug import Guard
 from unplug.integrations.langgraph import langgraph_input_node, langgraph_tool_guard
-from unplug.integrations.hooks import AgentHooks
 
-hooks = AgentHooks(Guard(mode="server")) # hosted API
 graph.add_node("unplug_gate", langgraph_input_node(hooks))
-
 tool_guard = langgraph_tool_guard(hooks)
-decision = tool_guard("shell_exec", {"command": "..."})
-if not decision.allowed:
- ...
-```
-
-Demo (no `langgraph` package required):
-
-```bash
-python examples/langgraph_hooks_demo.py
 ```
 
-## Agno
-
-```python
-from agno.agent import Agent
-from unplug import Guard
-from unplug.integrations.agno import agno_pre_run_hook, agno_post_run_hook, agno_tool_hook
-from unplug.integrations.hooks import AgentHooks
-
-hooks = AgentHooks(Guard())
-agent = Agent(
- pre_hooks=[agno_pre_run_hook(hooks)],
- # wire post_run / tool middleware per Agno version
-)
-```
-
-Demo:
-
-```bash
-python examples/agno_hooks_demo.py
-```
+Demo: `python examples/langgraph_hooks_demo.py`
 
 ## Haystack (RAG)
 
-The retrieval path is the blind spot in most injection defenses: a poisoned
-document in the store carries its payload straight into the prompt. The
-`UnplugDocumentGuard` component sits between the retriever and the prompt
-builder. It scans each retrieved `Document`, drops or redacts on findings, and
-boundary-wraps survivors so injected text cannot impersonate system
-instructions. See [`RAG_DEFENSE.md`](RAG_DEFENSE.md) for the threat model.
-
 ```python
-from haystack import Pipeline
-from unplug.integrations.haystack import UnplugDocumentGuard
-
-pipe = Pipeline()
-pipe.add_component("retriever", retriever)
-pipe.add_component("guard", UnplugDocumentGuard()) # Guard() under the hood
-pipe.add_component("prompt", prompt_builder)
-pipe.connect("retriever.documents", "guard.documents")
-pipe.connect("guard.documents", "prompt.documents")
+from unplug.integrations.haystack import UnplugDocumentGuard, scan_for_ingestion
 ```
 
-Defend at ingestion too, so poisoned content never reaches the store:
-
-```python
-from unplug import Guard
-from unplug.integrations.haystack import scan_for_ingestion
-
-decision = scan_for_ingestion(Guard(), document_text)
-if decision.index_ok:
- document.meta.update(decision.meta_update) # marks it pre-scanned
- document_store.write_documents([document])
-```
-
-Install: `pip install unplug-ai[haystack]`. The scanning core (`scan_document`,
-`scan_for_ingestion`) is import-safe without Haystack; only the component
-requires it.
+Install: `pip install unplug-ai[haystack]`. See [`RAG_DEFENSE.md`](RAG_DEFENSE.md).
 
 ## Hosted vs local
 
 | Setup | Guard init |
 |-------|------------|
-| Your VM + API key | `Guard(mode="server")` + `UNPLUG_API_KEY` |
-| Local sidecar | `Guard(mode="server", server_url="http://127.0.0.1:8000")` |
-| Embedded ML | `Guard()` + `active_model=tiny` |
+| Hosted API | `Guard(mode="server")` + `UNPLUG_API_KEY` |
+| Sidecar | `Guard(mode="server", server_url="http://127.0.0.1:8000")` |
+| Embedded | `Guard()` |
 
-See [`DEPLOYMENT.md`](DEPLOYMENT.md).
+Tool enforcement always runs locally. See [`DEPLOYMENT.md`](DEPLOYMENT.md).
 
-## Docker E2E (sidecar + examples)
+## Security testing
 
 ```bash
-cd sdk
-chmod +x scripts/docker_e2e.sh
-./scripts/docker_e2e.sh
-# or: make docker-e2e
+uv run pytest tests/security/test_agent_integration_matrix.py -v
 ```
 
-Builds `unplug-server` sidecar, waits for `/v1/health`, runs `local_sidecar_client.py` and `hosted_client.py`.
+See [`integrations/TESTING.md`](../integrations/TESTING.md) for all 40 angles.
+
+## Docker E2E (sidecar + examples)
+
+```bash
+cd sdk && make docker-e2e
+```
 
-## What is not included yet
+## MCP
 
-- Official PyPI extras `unplug-ai[langgraph]` / `[agno]` (hooks work without them)
-- Auto-instrumentation via `Guard.init()` (manual hooks only)
-- MCP / CrewAI / LlamaIndex wrappers (same `AgentHooks` pattern applies)
-- LlamaIndex `NodePostprocessor` equivalent of `UnplugDocumentGuard` (same `scan_document` core applies)
+For Claude / Cursor MCP server, use [`unplug-mcp`](https://github.com/UnplugAI/unplug-mcp) — see [`integrations/mcp/README.md`](../integrations/mcp/README.md).
diff --git a/sdk/integrations/README.md b/sdk/integrations/README.md
@@ -0,0 +1,89 @@
+# Agent framework integrations
+
+Unplug ships **framework-agnostic hooks first**. You do not need LangGraph, CrewAI, or any agent SDK to use the core Guard — install only the extra for the stack you run.
+
+## Quick start
+
+```bash
+pip install unplug-ai # core Guard (regex scanners, no agent deps)
+pip install "unplug-ai[langgraph]" # + LangGraph when you wire graph nodes
+pip install "unplug-ai[integrations]" # all documented agent/RAG framework extras
+pip install "unplug-ai[all]" # capability extras (ML, presidio, yara, scrape…)
+pip install "unplug-ai[all,integrations]" # everything: capabilities + every framework
+```
+
+Every integration module lives under `unplug.integrations.*` and uses the same five hook points:
+
+| Hook | When to call | Threats caught |
+|------|----------------|----------------|
+| `scan_user_input` | Before the LLM turn | Direct prompt injection, jailbreaks |
+| `wrap_retrieved_content` | After RAG / web fetch | Indirect injection in documents |
+| `before_tool_call` | Before every tool | Destructive shell/SQL, exfil, financial |
+| `scan_agent_output` | Before returning to user | Leaked secrets, harmful content |
+| `scan_request_isolated` | Eval / probes | Same scans without session taint bleed |
+
+```python
+from unplug import Guard
+from unplug.integrations.hooks import AgentHooks
+
+hooks = AgentHooks(Guard()) # or Guard(mode="server") for hosted API
+decision = hooks.scan_user_input(user_message)
+if not decision.allowed:
+ raise RuntimeError(decision.message)
+```
+
+## Supported frameworks
+
+| Framework | Extra | Guide | Code module |
+|-----------|-------|-------|-------------|
+| **Custom loop** | *(none)* | [custom-loop](custom-loop/README.md) | `hooks.py` |
+| **LangGraph** | `langgraph` | [langgraph](langgraph/README.md) | `langgraph.py` |
+| **Agno** | `agno` | [agno](agno/README.md) | `agno.py` |
+| **Haystack** | `haystack` | [haystack](haystack/README.md) | `haystack.py` |
+| **LlamaIndex** | `llama-index` | [llama-index](llama-index/README.md) | `llama_index.py` |
+| **CrewAI** | `crewai` | [crewai](crewai/README.md) | `crewai.py` |
+| **AutoGen** | `autogen` | [autogen](autogen/README.md) | `autogen.py` |
+| **Pydantic AI** | `pydantic-ai` | [pydantic-ai](pydantic-ai/README.md) | `pydantic_ai.py` |
+| **Semantic Kernel** | `semantic-kernel` | [semantic-kernel](semantic-kernel/README.md) | `semantic_kernel.py` |
+| **MCP clients** | `mcp` | [mcp](mcp/README.md) | [unplug-mcp](https://github.com/UnplugAI/unplug-mcp) |
+
+Demos (no framework install required for LangGraph / Agno patterns):
+
+```bash
+cd sdk
+python examples/langgraph_hooks_demo.py
+python examples/agno_hooks_demo.py
+```
+
+## Deployment modes
+
+| Mode | Guard init | Tool enforcement |
+|------|------------|------------------|
+| Embedded (local) | `Guard()` | Local `check_tool_call` |
+| Hosted API | `Guard(mode="server", server_url=..., server_api_key=...)` | **Always local** — never delegate tool policy to the network |
+| Sidecar | `Guard(mode="server", server_url="http://127.0.0.1:8000")` | Local |
+
+See [`docs/DEPLOYMENT.md`](../docs/DEPLOYMENT.md).
+
+## Security testing
+
+We maintain a **40-angle integration security matrix** exercised in CI. See [TESTING.md](TESTING.md) for the full list and how to run it locally:
+
+```bash
+cd sdk
+uv run pytest tests/security/test_agent_integration_matrix.py -v
+```
+
+## Contributing a new integration
+
+1. Copy [`_template.md`](_template.md)
+2. Add hooks in `src/unplug/integrations/<name>.py` (no hard dependency at import time)
+3. Add optional extra in `pyproject.toml`
+4. Add matrix cases in `tests/security/test_agent_integration_matrix.py`
+5. Link from this README
+
+## Related docs
+
+- [`docs/INTEGRATIONS.md`](../docs/INTEGRATIONS.md) — API reference (compact)
+- [`docs/RAG_DEFENSE.md`](../docs/RAG_DEFENSE.md) — retrieval-path threat model
+- [`docs/DEPLOYMENT.md`](../docs/DEPLOYMENT.md) — local vs hosted vs sidecar