11# Agent framework integrations
22
3- 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.
3+ > ** Full guides:** [ ` integrations/README.md ` ] ( ../integrations/README.md ) — per-framework wiring, extras, and the [ 40-angle security matrix] ( ../integrations/TESTING.md ) .
4+
5+ Unplug ships ** framework-agnostic hooks** first. Install only the extra for your stack:
6+
7+ ``` bash
8+ pip install unplug-ai # core — no agent SDK deps
9+ pip install " unplug-ai[langgraph]" # LangGraph
10+ pip install " unplug-ai[crewai]" # CrewAI
11+ pip install " unplug-ai[integrations]" # all documented agent/RAG extras
12+ ```
413
514## Core: ` AgentHooks `
615
@@ -21,115 +30,68 @@ tool_decision = hooks.before_tool_call("send_email", {"to": "...", "body": "..."
2130| Hook | When to call |
2231| ------| ----------------|
2332| ` scan_user_input ` | Before LLM turn |
24- | ` wrap_retrieved_content ` | After RAG / web fetch, before context insert |
25- | ` before_tool_call ` | Before every tool execution (always local, even in server mode) |
26- | ` scan_agent_output ` | Before returning response to user |
27- | ` scan_request_isolated ` | Eval / probes (no session taint bleed) |
33+ | ` wrap_retrieved_content ` | After RAG / web fetch |
34+ | ` before_tool_call ` | Before every tool (always local) |
35+ | ` scan_agent_output ` | Before returning to user |
36+ | ` scan_request_isolated ` | Eval / probes (no session bleed) |
37+
38+ ## Framework modules
39+
40+ | Framework | Extra | Module |
41+ | -----------| -------| --------|
42+ | LangGraph | ` langgraph ` | ` unplug.integrations.langgraph ` |
43+ | Agno | ` agno ` | ` unplug.integrations.agno ` |
44+ | CrewAI | ` crewai ` | ` unplug.integrations.crewai ` |
45+ | AutoGen | ` autogen ` | ` unplug.integrations.autogen ` |
46+ | Haystack | ` haystack ` | ` unplug.integrations.haystack ` |
47+ | LlamaIndex | ` llama-index ` | ` unplug.integrations.llama_index ` |
48+ | Pydantic AI | ` pydantic-ai ` | ` unplug.integrations.pydantic_ai ` |
49+ | Semantic Kernel | ` semantic-kernel ` | ` unplug.integrations.semantic_kernel ` |
50+ | Custom loop | * (none)* | ` unplug.integrations.hooks ` |
2851
2952## LangGraph
3053
3154``` python
32- from unplug import Guard
3355from unplug.integrations.langgraph import langgraph_input_node, langgraph_tool_guard
34- from unplug.integrations.hooks import AgentHooks
3556
36- hooks = AgentHooks(Guard(mode = " server" )) # hosted API
3757graph.add_node(" unplug_gate" , langgraph_input_node(hooks))
38-
3958tool_guard = langgraph_tool_guard(hooks)
40- decision = tool_guard(" shell_exec" , {" command" : " ..." })
41- if not decision.allowed:
42- ...
43- ```
44-
45- Demo (no ` langgraph ` package required):
46-
47- ``` bash
48- python examples/langgraph_hooks_demo.py
4959```
5060
51- ## Agno
52-
53- ``` python
54- from agno.agent import Agent
55- from unplug import Guard
56- from unplug.integrations.agno import agno_pre_run_hook, agno_post_run_hook, agno_tool_hook
57- from unplug.integrations.hooks import AgentHooks
58-
59- hooks = AgentHooks(Guard())
60- agent = Agent(
61- pre_hooks = [agno_pre_run_hook(hooks)],
62- # wire post_run / tool middleware per Agno version
63- )
64- ```
65-
66- Demo:
67-
68- ``` bash
69- python examples/agno_hooks_demo.py
70- ```
61+ Demo: ` python examples/langgraph_hooks_demo.py `
7162
7263## Haystack (RAG)
7364
74- The retrieval path is the blind spot in most injection defenses: a poisoned
75- document in the store carries its payload straight into the prompt. The
76- ` UnplugDocumentGuard ` component sits between the retriever and the prompt
77- builder. It scans each retrieved ` Document ` , drops or redacts on findings, and
78- boundary-wraps survivors so injected text cannot impersonate system
79- instructions. See [ ` RAG_DEFENSE.md ` ] ( RAG_DEFENSE.md ) for the threat model.
80-
8165``` python
82- from haystack import Pipeline
83- from unplug.integrations.haystack import UnplugDocumentGuard
84-
85- pipe = Pipeline()
86- pipe.add_component(" retriever" , retriever)
87- pipe.add_component(" guard" , UnplugDocumentGuard()) # Guard() under the hood
88- pipe.add_component(" prompt" , prompt_builder)
89- pipe.connect(" retriever.documents" , " guard.documents" )
90- pipe.connect(" guard.documents" , " prompt.documents" )
66+ from unplug.integrations.haystack import UnplugDocumentGuard, scan_for_ingestion
9167```
9268
93- Defend at ingestion too, so poisoned content never reaches the store:
94-
95- ``` python
96- from unplug import Guard
97- from unplug.integrations.haystack import scan_for_ingestion
98-
99- decision = scan_for_ingestion(Guard(), document_text)
100- if decision.index_ok:
101- document.meta.update(decision.meta_update) # marks it pre-scanned
102- document_store.write_documents([document])
103- ```
104-
105- Install: ` pip install unplug-ai[haystack] ` . The scanning core (` scan_document ` ,
106- ` scan_for_ingestion ` ) is import-safe without Haystack; only the component
107- requires it.
69+ Install: ` pip install unplug-ai[haystack] ` . See [ ` RAG_DEFENSE.md ` ] ( RAG_DEFENSE.md ) .
10870
10971## Hosted vs local
11072
11173| Setup | Guard init |
11274| -------| ------------|
113- | Your VM + API key | ` Guard(mode="server") ` + ` UNPLUG_API_KEY ` |
114- | Local sidecar | ` Guard(mode="server", server_url="http://127.0.0.1:8000") ` |
115- | Embedded ML | ` Guard() ` + ` active_model=tiny ` |
75+ | Hosted API | ` Guard(mode="server") ` + ` UNPLUG_API_KEY ` |
76+ | Sidecar | ` Guard(mode="server", server_url="http://127.0.0.1:8000") ` |
77+ | Embedded | ` Guard() ` |
11678
117- See [ ` DEPLOYMENT.md ` ] ( DEPLOYMENT.md ) .
79+ Tool enforcement always runs locally. See [ ` DEPLOYMENT.md ` ] ( DEPLOYMENT.md ) .
11880
119- ## Docker E2E (sidecar + examples)
81+ ## Security testing
12082
12183``` bash
122- cd sdk
123- chmod +x scripts/docker_e2e.sh
124- ./scripts/docker_e2e.sh
125- # or: make docker-e2e
84+ uv run pytest tests/security/test_agent_integration_matrix.py -v
12685```
12786
128- Builds ` unplug-server ` sidecar, waits for ` /v1/health ` , runs ` local_sidecar_client.py ` and ` hosted_client.py ` .
87+ See [ ` integrations/TESTING.md ` ] ( ../integrations/TESTING.md ) for all 40 angles.
88+
89+ ## Docker E2E (sidecar + examples)
90+
91+ ``` bash
92+ cd sdk && make docker-e2e
93+ ```
12994
130- ## What is not included yet
95+ ## MCP
13196
132- - Official PyPI extras ` unplug-ai[langgraph] ` / ` [agno] ` (hooks work without them)
133- - Auto-instrumentation via ` Guard.init() ` (manual hooks only)
134- - MCP / CrewAI / LlamaIndex wrappers (same ` AgentHooks ` pattern applies)
135- - LlamaIndex ` NodePostprocessor ` equivalent of ` UnplugDocumentGuard ` (same ` scan_document ` core applies)
97+ For Claude / Cursor MCP server, use [ ` unplug-mcp ` ] ( https://github.com/UnplugAI/unplug-mcp ) — see [ ` integrations/mcp/README.md ` ] ( ../integrations/mcp/README.md ) .
0 commit comments