Metadata-Version: 2.4
Name: inter-agent-guard
Version: 1.1.0
Summary: Inter-agent security firewall for multi-agent AI systems
License: Apache-2.0
License-File: LICENSE
Keywords: agents,security,firewall,langchain,langgraph,prompt-injection,multi-agent
Author: AgentGuard Contributors
Requires-Python: >=3.11,<3.13
Classifier: License :: OSI Approved :: Apache Software License
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Provides-Extra: all
Provides-Extra: autogen
Provides-Extra: crewai
Provides-Extra: langchain
Provides-Extra: langgraph
Provides-Extra: otel
Requires-Dist: PyYAML (>=6.0)
Requires-Dist: crewai (>=0.70) ; extra == "crewai" or extra == "all"
Requires-Dist: jsonschema (>=4.0)
Requires-Dist: langchain (>=1.0) ; extra == "langchain" or extra == "all"
Requires-Dist: langgraph (>=0.2) ; extra == "langgraph" or extra == "all"
Requires-Dist: numpy (>=1.26)
Requires-Dist: onnxruntime (>=1.17)
Requires-Dist: opentelemetry-exporter-otlp (>=1.24) ; extra == "otel"
Requires-Dist: opentelemetry-sdk (>=1.24) ; extra == "otel"
Requires-Dist: pyahocorasick (>=2.0)
Requires-Dist: pyautogen (>=0.4) ; extra == "autogen" or extra == "all"
Requires-Dist: pynacl (>=1.5)
Requires-Dist: sentence-transformers (>=2.7)
Requires-Dist: sentencepiece (>=0.2)
Requires-Dist: structlog (>=24.0)
Requires-Dist: transformers (>=4.40)
Project-URL: Documentation, https://inter-agent-guard.readthedocs.io/
Project-URL: Homepage, https://github.com/nizba06/agentguard
Project-URL: Repository, https://github.com/nizba06/agentguard
Description-Content-Type: text/markdown

# AgentGuard

Inter-agent security firewall for multi-agent AI systems (LangChain, LangGraph, CrewAI, AutoGen).

**PyPI:** `pip install inter-agent-guard` · **Import / CLI:** `agentguard`  
**Docs:** [inter-agent-guard.readthedocs.io](https://inter-agent-guard.readthedocs.io/) · [Blog post](docs/BLOG_POST.md) · [Demo](https://github.com/nizba06/inter-agent-guard-demo)

> **Docs not loading yet?** Import the repo on Read the Docs once — see [docs/READTHEDOCS_SETUP.md](docs/READTHEDOCS_SETUP.md). Until then: [quickstart on GitHub](https://github.com/nizba06/agentguard/blob/master/docs/source/quickstart.md).

AgentGuard intercepts every message between agents and enforces three runtime controls:

1. **Message Inspector** — Aho-Corasick rule filter + DeBERTa ML scorer + consistency check
2. **Trust Verifier** — Ephemeral Ed25519 signing via PyNaCl
3. **Capability Enforcer** — YAML manifests with JSON Schema validation and monotonic attenuation

## Quick start

```bash
# Python 3.11 or 3.12
pip install "inter-agent-guard[all,otel]"
# ONNX weights are not in the wheel (~164 MB INT8) — from a clone:
python scripts/download_release_model.py
# or: download risk_scorer.onnx + model.sha256 from GitHub Releases into agentguard/models/

agentguard status
agentguard check-manifest manifests/comms_agent.yaml
agentguard inspect -m "Summarise public pricing data from filings."
```

> **Note:** The PyPI project is `inter-agent-guard` because bare `agentguard` collides with existing `agent-guard` under PyPI’s name rules. The Python import and CLI remain `agentguard`.

```python
from agentguard import AgentGuard, CapabilityManifest

guard = AgentGuard(
    risk_threshold=0.85,
    task_objective="Analyse Q3 competitor pricing",
    audit_log_path="./audit.jsonl",
    # Set True in production after installing the ONNX model
    require_ml_model=True,
)
guard.register_agent(
    "research-agent",
    CapabilityManifest.from_yaml("manifests/research_agent.yaml"),
)
secured_graph = guard.wrap(my_langgraph_graph)
```

Without the ONNX model, rule filtering and trust attestation still run; ML scoring is inactive.

## Framework adapters — which to use

| Integration | Production readiness | Notes |
|-------------|---------------------|--------|
| **LangChain `AgentGuardMiddleware`** | Recommended | Official `create_agent` middleware API |
| **Direct `inspect_*` / `wrap_mcp_tool`** | Recommended | Framework-agnostic; full control |
| **`guard.wrap(langgraph_graph)`** | Supported | Patches compiled LangGraph nodes |
| **CrewAI / AutoGen adapters** | Best-effort | Monkey-patch private APIs; emit a `UserWarning`; mock-tested only |

## LangChain agents (official middleware)

AgentGuard plugs into LangChain 1.0's `create_agent` as standard [agent middleware](https://docs.langchain.com/oss/python/langchain/middleware/custom) — no monkey-patching, sync and async:

```bash
pip install "inter-agent-guard[langchain]"
```

```python
from langchain.agents import create_agent
from agentguard import AgentGuard
from agentguard.adapters.langchain import AgentGuardMiddleware

guard = AgentGuard(task_objective="Analyse Q3 competitor pricing")
agent = create_agent(
    model="gpt-5.5",
    tools=[fetch_page, search],
    middleware=[AgentGuardMiddleware(guard, agent_id="researcher")],
)
```

On every run the middleware:

- **Scans user input** before the first model call (`before_agent`)
- **Inspects every tool output** for indirect prompt injection / MCP poisoning before the model sees it (`wrap_tool_call`)
- **Enforces capability manifests** before tools execute (register one under `agent_id`)

Flagged content is replaced with a safe notice by default (`on_violation="replace"`), or raises `AgentGuardException` (`on_violation="raise"`). `mode="monitor"` audits without blocking. Try it offline:

```bash
python examples/langchain_middleware_example.py
```

## Latency and deployment modes

CPU ONNX P95 is ~3.4 s on holdout (design target was 15 ms). Choose a mode that fits your budget:

| Mode | How | When |
|------|-----|------|
| **Rules-only** | `require_ml_model=False` (no ONNX) | Lowest latency; patterns + capability + trust |
| **Monitor** | `mode="monitor"` | Shadow deploy; audit without blocking |
| **Enforce + ML (CPU)** | `require_ml_model=True` | Highest detection; accept ~3 s P95 |
| **Enforce + ML (GPU)** | Install `onnxruntime-gpu` | Lower ML latency when CUDA is available |
| **Async / selective hops** | Rules on hot path; ML off-path | High-frequency graphs |

Full guide: [Latency / deployment modes](https://inter-agent-guard.readthedocs.io/en/latest/latency.html) ([source](docs/source/latency.md)).

## Production setup

1. **Install the ML model** (required for enforce-mode ML scoring):

   ```bash
   python scripts/download_release_model.py
   python scripts/verify_model.py
   ```

   ```powershell
   py -3.12 scripts\download_release_model.py
   py -3.12 scripts\verify_model.py
   ```

   Or copy artifacts you already have:

   ```bash
   ./scripts/install_model.sh ./path/to/model/dir
   # PowerShell: .\scripts\install_model.ps1 -SourceDir .\path\to\model\dir
   ```

   Sources: [GitHub Releases v1.0.0](https://github.com/nizba06/agentguard/releases/tag/v1.0.0), local training, or Kaggle (`.\scripts\download_kaggle_model.ps1`).

2. **Confirm health**:

   ```bash
   agentguard status
   ```

3. **Optional — benchmark on holdout** (v1.0 source of truth):

   ```powershell
   .\scripts\run_benchmark_evaluation.ps1 -Holdout -RequireModel
   py -3.12 scripts/check_v1_gates.py --allow-cpu-latency
   ```

4. **Run secured demo**:

   ```bash
   poetry run python examples/secured_pipeline/pipeline.py
   ```

Novel v1.0 corpus is on [Hugging Face](https://huggingface.co/datasets/Nizba/agentguard-benchmark-v1). To regenerate locally, see [docs/ANTHROPIC_DATASET_RUNBOOK.md](docs/ANTHROPIC_DATASET_RUNBOOK.md).

### Trust attestation (envelope signatures)

Inter-agent hops require a recipient-bound signature (`inter-agent-guard` ≥ 1.1.0):

```python
payload = b"Research summary ready for internal report."
sig = guard.sign_payload("researcher", payload, recipient_id="writer")
decision = guard.inspect_message(
    "researcher", "writer", payload.decode(), payload, signature=sig,
)
```

Use `inspect_content(...)` for unsigned boundaries (user input, framework hooks).
Persist audits with `inspect --audit-log ./audit.jsonl`, then `agentguard verify`.

### CLI

```bash
agentguard version
agentguard status [--json]
agentguard check-manifest manifests/comms_agent.yaml [--json]
agentguard inspect -m "message text" [--audit-log ./audit.jsonl] [--json]
agentguard verify ./audit.jsonl [--json]
```

### Docker

Core runtime image (firewall + OTEL; LangGraph/CrewAI/AutoGen installed separately in app images):

```bash
docker build -t agentguard .
docker run --rm agentguard
docker run --rm -v "%CD%\audit.jsonl:/data/audit.jsonl" agentguard verify /data/audit.jsonl
```

For framework adapters in your own Dockerfile: `pip install "inter-agent-guard[all,otel]"`.

Optional OpenTelemetry export (requires `pip install "inter-agent-guard[otel]"`):

```python
guard = AgentGuard(enable_otel_export=True, audit_log_path="./audit.jsonl")
```

Set `OTEL_EXPORTER_OTLP_ENDPOINT` to auto-configure the OTLP exporter.

## Capability enforcement

Manifests declare tools, data sources, endpoints, token limits, and delegation. At runtime:

| API | Enforces |
|-----|----------|
| `check_tool_call(agent, tool, endpoint=...)` | `permitted_tools`, `forbidden_tools`, optional `permitted_endpoints` |
| `check_endpoint(agent, url)` | `external_contact` + `permitted_endpoints` |
| `check_data_source(agent, source)` | `allowed_data_sources` |
| `check_output_tokens(agent, n)` | `max_output_tokens` |
| `register_delegated_agent(...)` | `can_spawn_agents`, `max_delegation_depth`, monotonic attenuation |

See example manifests under `manifests/` (including `comms_agent.yaml` with endpoint allowlists).

## Examples

```bash
# Vulnerable baseline (100% attack success)
poetry run python examples/vulnerable_pipeline/pipeline.py

# AgentGuard-protected version
poetry run python examples/secured_pipeline/pipeline.py

# MCP poisoning, CrewAI, AutoGen
poetry run python examples/mcp_poisoning_demo.py
poetry run python examples/crewai_example.py
poetry run python examples/autogen_example.py
```

## Benchmark

AgentGuard ships with a 6,200-example inter-agent benchmark (1,200 adversarial + 5,000 benign).

**Published on Hugging Face:** [Nizba/agentguard-benchmark-v1](https://huggingface.co/datasets/Nizba/agentguard-benchmark-v1) (Anthropic Batch, `anthropic_batch_v1`).

### Build dataset locally (zero cost, optional)

```powershell
.\scripts\run_public_dataset_build.ps1
```

Sources: InjecAgent (GitHub) + inter-agent framing templates + pipeline-style benign messages.

### Run evaluation

**Holdout** (uncontaminated — use for v1.0 gating):

```powershell
.\scripts\run_benchmark_evaluation.ps1 -Holdout -RequireModel
```

Results: `benchmarks/results/holdout_report.md`

Full corpus (may overlap training data — not a ship gate):

```powershell
.\scripts\run_benchmark_evaluation.ps1 -RequireModel
```

Results: `benchmarks/results/report.md`

### Latest results — **holdout is the v1.0 source of truth**

Uncontaminated 20% holdout (`benchmarks/dataset/holdout/`, 160 adversarial + 1,000 benign), **INT8 ONNX** (2026-07-15):

| Metric | Holdout | v1.0 gate |
|--------|---------|-----------|
| Overall detection rate | **99.4%** | > 90% |
| False positive rate | **0.0%** | < 3% |
| P95 inspection latency | ~3.4 s (CPU INT8) | < 15 ms **or** published GPU/async SLA |
| ONNX model size | ~164 MB INT8 | < 180 MB |
| ML model loaded | Yes (`verify_model.py` PASS) | Required for enforce+ML |

Package version: **1.1.0** (ONNX assets still published under GitHub release **v1.0.0**). CPU ML P95 does not meet the original 15 ms design target — use rules-only, GPU, or async for high-QPS (see [latency guide](https://inter-agent-guard.readthedocs.io/en/latest/latency.html)).

```powershell
.\scripts\run_benchmark_evaluation.ps1 -Holdout -RequireModel
py -3.12 scripts/check_v1_gates.py --allow-cpu-latency
```

Reproduce with the HF corpus or local `benchmarks/dataset/*.jsonl` after a verified model install. See [docs/V1_ROADMAP.md](docs/V1_ROADMAP.md).

### vs Microsoft Agent Governance Toolkit

Feature matrix and shared-dataset methodology: [docs/MICROSOFT_TOOLKIT_COMPARISON.md](docs/MICROSOFT_TOOLKIT_COMPARISON.md).

```powershell
py -3.12 scripts\run_toolkit_comparison.py
```

## Training (Kaggle GPU)

```powershell
.\scripts\push_kaggle_kernel.ps1   # uploads code dataset + pushes notebook
```

Open kernel on Kaggle → GPU T4 x2 + Internet → Run All. Copy `agentguard/models/*` from Output tab.

See [training/kaggle_notebook.ipynb](training/kaggle_notebook.ipynb).

## Documentation

- **[Read the Docs](https://inter-agent-guard.readthedocs.io/)** — quickstart, latency, API (import repo once: [setup guide](docs/READTHEDOCS_SETUP.md))
- [Technical blog](docs/BLOG_POST.md)
- [Microsoft toolkit comparison](docs/MICROSOFT_TOOLKIT_COMPARISON.md)
- [CONTRIBUTING.md](CONTRIBUTING.md)
- [REQUIREMENTS.md](docs/REQUIREMENTS.md)
- [DESIGN.md](docs/DESIGN.md)
- [Release notes v1.1.0](docs/RELEASE_NOTES_v1.1.0.md)
- [Release notes v1.0.0](docs/RELEASE_NOTES_v1.0.0.md)
- [Launch checklist](scripts/LAUNCH_CHECKLIST.md)
- [Hugging Face dataset card](docs/HUGGINGFACE_DATASET_CARD.md)

Build docs locally:

```bash
poetry install --with docs
sphinx-build -b html docs/source docs/_build/html
# open docs/_build/html/index.html
```

## License

Apache-2.0 — see [LICENSE](LICENSE).

