DESIGN.md

AgentGuard

Inter-Agent Security Firewall

Design Document & Developer Setup Guide

Version 1.0 • June 2026 • 3-Week Build Sprint

Historical document — design-time targets, not measurements. Several figures below were never achieved and are retained to show intent:

Claim in this document	Reality
ML scorer ~12ms	~415ms P95 on the shipped INT8 CPU path. The 12ms figure was a GPU-class estimate.
94%+ detection on InjectAgent	InjectAgent was never run. The only evaluation used a self-generated corpus.
ONNX 91MB	The shipped INT8 artifact is ~164MB.

The v1 ML detection numbers are withdrawn (that scorer classified on message length). v1.2.0 is validated on deepset/prompt-injections test (90% / 0% FPR) vs a length ruler. See KNOWN_LIMITATIONS.md. Holdout P95 on CPU is ~3.3 s, not the ~12 ms design-time figure below.

IDE VS Code

Language Python 3.11

Target 3 weeks

1. Project Overview

AgentGuard is an open-source security middleware library for multi-agent AI systems. It intercepts every message passing between agents in a LangGraph, CrewAI, or AutoGen pipeline and enforces three runtime security controls: message inspection, cryptographic trust attestation, and capability containment. It ships alongside a purpose-built benchmark — the first published evaluation suite specifically targeting inter-agent injection attacks.

This document covers the complete technical design and the step-by-step setup guide to go from zero to a running development environment in under 30 minutes.

What makes this different from everything that exists Every existing guardrails tool — LLM Guard, NeMo Guardrails, Rebuff — operates at the user-to-model boundary. None inspect messages between agents. AgentGuard is the first open-source tool to treat inter-agent messages as untrusted inputs requiring independent inspection, signing, and scope enforcement at every hop.

1.1 Three Core Security Layers

Layer	What it does
Layer 1 — Message Inspector	Hybrid rule-and-ML classifier scores every inter-agent message (and MCP tool outputs) for injection risk before delivery. Three stages: rule pre-filter (<0.5ms), DeBERTa ML scorer (~12ms), contextual consistency check (~4ms).
Layer 2 — Trust Verifier	Each agent is issued an ephemeral Ed25519 keypair at pipeline initialisation. Every message is signed by the sender and verified before the recipient acts on it. Keys are rotated per run — no replay attacks.
Layer 3 — Capability Enforcer	Each agent declares a YAML capability manifest specifying permitted tools, forbidden tools, allowed data sources, and external contact rules. Violations are blocked at runtime, not logged after the fact.
Audit Logger	Every processed message is written to an append-only cryptographically chained JSONL audit log. Each entry includes the SHA-256 hash of the previous entry — tampering is detectable. Optional OpenTelemetry export.
Benchmark Suite	The first published inter-agent injection benchmark. 1,200 adversarial messages crafted specifically to exploit inter-agent trust assumptions. Reusable by any researcher evaluating their own defences.

2. Technology Stack

Every technology choice below is made for three reasons specific to this project: it minimises friction in a 3-week solo build, it is the best tool for the specific technical job, and it avoids dependencies that would complicate open-source adoption.

2.1 IDE & AI Tooling

Primary IDE: VS Code

Any VS Code-compatible editor works. For AgentGuard you will frequently need to edit the inspector module, its integration test, and the LangGraph adapter in one change. The Python, Pylance, Ruff, and Docker extensions are enough.

Feature	Why it matters for this build
Python / Pylance / Ruff	Same extensions as any VS Code setup. No special toolchain.
Multi-file edits	Inspector, tests, and adapters often change together.
Pre-commit hooks	Ruff, mypy, and pytest run on every commit.
Cost	VS Code is free.

Terminal Companion: Claude Code

Claude Code is Anthropic's terminal-based coding agent, included with Claude Pro. Use it for heavier generation tasks: writing full modules from a spec, generating the benchmark dataset (1,200 adversarial messages), writing the complete test suite, and producing the README and blog post draft. It operates on your local file system and is faster than chat for bulk code generation.

How to split the work Use VS Code for day-to-day coding, debugging, multi-file edits, and running tests. Use a terminal coding agent for generating entire new modules from scratch, bulk dataset generation, writing 500+ line test files, and documentation drafts.

2.2 Language & Package Management

Tool	Choice & Reasoning
Python version	3.11 specifically. LangGraph 0.2, CrewAI 0.70, and AutoGen 0.4 all have the most stable support on 3.11. Python 3.12 works but introduces minor asyncio changes that cause intermittent issues with LangGraph's StateGraph — not worth the debugging time on a 3-week sprint.
Version management	pyenv. Lets you install and switch Python versions without touching the system Python. Critical when your machine may have 3.9 or 3.10 as the system default.
Package management	Poetry. Two reasons: (1) pyproject.toml-native dependency locking means your exact environment is reproducible, (2) poetry publish pushes to PyPI in one command with no separate setup.py or twine configuration. This matters for Week 3 when you launch.
Linting & formatting	Ruff. Replaces flake8 + isort + black in a single tool running in milliseconds. Configured once in pyproject.toml. Pre-commit hook runs it automatically so the codebase stays clean without thinking about it.
Type checking	mypy with strict mode on the core modules (firewall.py, inspector/, trust/, capability/). Catches bugs that tests miss. Not required everywhere — just the security-critical paths.

2.3 Agent Framework Targets

AgentGuard wraps three frameworks. Build in this order — LangGraph first because it has the largest user base and the clearest interception points.

Framework	Version	Integration approach
LangGraph	>=0.2	Wrap the compiled StateGraph with guard.wrap(graph). Intercepts at the node execution boundary using LangGraph's custom node wrapper pattern. This is the primary adapter — build in Week 1.
CrewAI	>=0.70	Hook into the agent.execute_task lifecycle and the tool execution pipeline. CrewAI's architecture makes tool-call interception straightforward. Build in Week 2.
AutoGen	>=0.4	Middleware on the GroupChat.run_chat message passing interface. AutoGen's message bus is well-structured for interception. Build in Week 3.

2.4 Security & Cryptography

Library	Choice & Reasoning
PyNaCl (Ed25519 signing)	libsodium bindings for Python. Ed25519 chosen over RSA because: 64-byte signatures (vs 256+ for RSA), constant-time verification (side-channel resistant), and the PyNaCl API is simple enough that the signing layer can be implemented in under 100 lines. pip install pynacl.
pyahocorasick (rule filter)	Aho-Corasick multi-pattern string matching. Searches for all injection signature patterns simultaneously in O(n) time — critical for keeping the rule-filter under 0.5ms even with 200+ patterns. Pure C with Python bindings. pip install pyahocorasick.
hashlib (audit log chaining)	Python standard library. SHA-256 for message hashes and log entry chaining. No external dependency needed.
jsonschema (manifest validation)	Validates YAML capability manifests against the published JSON Schema at registration time. Fails fast with descriptive errors before the pipeline starts. pip install jsonschema.
PyYAML (manifest loading)	Standard YAML parser for capability manifest files. pip install pyyaml.

2.5 ML Classifier Stack

Component	Choice & Reasoning
Model: DeBERTa-v3-small	Microsoft's DeBERTa-v3-small via Hugging Face. Chosen over DistilBERT (lower accuracy on adversarial text) and full DeBERTa-base (too large at 180MB, too slow at ~40ms CPU). The -small variant hits the right trade-off: 91MB ONNX, ~12ms CPU inference, 94%+ injection detection precision on the InjectAgent benchmark.
Fine-tuning: Hugging Face Trainer	Standard transformers Trainer API. Familiar to the research community, easy to reproduce, and the training script is simple enough to fit in a single notebook. Run on Kaggle free GPU (30 hrs/week) — no local GPU required.
Export: Hugging Face Optimum	Exports the fine-tuned model to ONNX format via optimum-cli. The ONNX file is framework-independent — no PyTorch or TensorFlow required at deployment time. pip install optimum[onnxruntime].
Inference: onnxruntime	Runs the ONNX model in-process, CPU-only by default, with optional GPU acceleration via onnxruntime-gpu. The model loads once at pipeline initialisation and stays in memory. pip install onnxruntime.
Consistency check: sentence-transformers	all-MiniLM-L6-v2 for semantic similarity between message intent and declared task objective. Fast (384-dim embeddings), small (80MB), and runs in-process. pip install sentence-transformers.
GPU for training	Kaggle (free, 30 GPU hrs/week) or Google Colab Pro ($12/month). Training takes 2-4 hours. No local GPU needed.

2.6 Testing Stack

Tool	Purpose & Reasoning
pytest	Standard Python test runner. pytest-asyncio extension for testing async agent pipelines. Target: >85% line coverage across all core modules.
hypothesis	Property-based testing. Generates random message variants automatically and checks that the firewall's behaviour is consistent. Particularly useful for the rule filter — catches edge cases that hand-written tests miss.
pytest-cov	Coverage measurement and reporting. Integrated with GitHub Actions to block PRs that drop coverage below 85%.
Custom attack fixtures	A set of pytest fixtures that fire all five attack classes (indirect injection, propagation, impersonation, capability escalation, MCP poisoning) against the reference vulnerable pipeline. These fixtures become the benchmark evaluation harness.

2.7 Packaging, CI/CD & Deployment

Tool	Purpose & Reasoning
GitHub Actions	CI/CD pipeline: runs Ruff lint, mypy type check, pytest suite, ONNX model integrity check, and benchmark regression on every PR. Publishes to PyPI automatically on version tags. Free for public repositories.
PyPI	pip install agentguard. Poetry handles the build and publish steps. The PyPI download count becomes one of your measurable adoption metrics.
Docker Hub	Multi-stage Docker image for teams who prefer a sidecar deployment pattern rather than pip install. The image is < 400MB including the ONNX model.
pre-commit	Runs Ruff and mypy automatically before every git commit. Enforces code quality without a CI round-trip. pip install pre-commit.
structlog	Structured JSONL logging for the audit trail. Produces machine-readable log entries with consistent field names. pip install structlog.
opentelemetry-sdk	Optional OTLP export for SIEM integration (Datadog, Splunk, Elastic). Installed separately as an optional dependency. pip install opentelemetry-sdk opentelemetry-exporter-otlp.

2.8 Complete Dependency Summary

# pyproject.toml — core dependencies [tool.poetry.dependencies] python = '>=3.11,<3.13' # Agent framework adapters langgraph = '>=0.2' crewai = '>=0.70' pyautogen = '>=0.4' # Security & crypto pynacl = '>=1.5' pyahocorasick = '>=2.0' jsonschema = '>=4.0' PyYAML = '>=6.0' # ML inference (no PyTorch at runtime) onnxruntime = '>=1.17' sentence-transformers = '>=2.7' numpy = '>=1.26' # Logging & observability structlog = '>=24.0' [tool.poetry.extras] otel = ['opentelemetry-sdk', 'opentelemetry-exporter-otlp'] [tool.poetry.dev-dependencies] pytest = '>=8.0' pytest-asyncio = '>=0.23' pytest-cov = '>=5.0' hypothesis = '>=6.0' ruff = '>=0.4' mypy = '>=1.9' pre-commit = '>=3.7' # Fine-tuning only (not shipped with the package) transformers = { version='>=4.40', optional=true } optimum = { version='>=1.19', optional=true, extras=['onnxruntime'] } datasets = { version='>=2.19', optional=true }

3. System Architecture

3.1 Data Flow

EXTERNAL WORLD (web, docs, APIs, MCP servers) | v untrusted input [ ORCHESTRATOR AGENT ] | v signs message with ephemeral Ed25519 key ╔═══════════════════════════════════════════════╗ ║ AGENTGUARD FIREWALL LAYER ║ ║ ║ ║ Stage 1: Rule filter <0.5ms ║ ║ Stage 2: ML risk scorer ~12ms ║ ║ Stage 3: Consistency check ~4ms ║ ║ Stage 4: Trust verify <1ms ║ ║ Stage 5: Capability check <1ms ║ ║ ║ ║ PASS → forward FAIL → quarantine + alert ║ ╚═══════════════════════════════════════════════╝ | | | v v v Research Code Comms Agent Agent Agent (read-only) (code exec) (email/Slack)

3.2 Repository Structure

agentguard/ ├── agentguard/ │ ├── __init__.py # Public API: AgentGuard, CapabilityManifest │ ├── firewall.py # Main class — entry point │ ├── inspector/ │ │ ├── rule_filter.py # Aho-Corasick rule-based pre-filter │ │ ├── ml_scorer.py # DeBERTa ONNX inference wrapper │ │ └── consistency.py # Sentence-transformer consistency check │ ├── trust/ │ │ ├── authority.py # Ephemeral keypair generation │ │ └── signing.py # Ed25519 sign & verify (PyNaCl) │ ├── capability/ │ │ ├── manifest.py # YAML loading + JSON Schema validation │ │ └── enforcer.py # Runtime capability enforcement │ ├── adapters/ │ │ ├── langgraph.py # LangGraph StateGraph wrapper │ │ ├── crewai.py # CrewAI tool + agent hook │ │ └── autogen.py # AutoGen GroupChat middleware │ ├── mcp/ │ │ └── output_inspector.py # MCP tool return value inspection │ └── audit/ │ ├── logger.py # Chained append-only JSONL logger │ └── otel.py # Optional OpenTelemetry OTLP export ├── schemas/ │ └── capability_manifest.schema.json ├── manifests/ # Example capability manifests ├── examples/ │ ├── vulnerable_pipeline/ # Reference attack demo │ └── secured_pipeline/ # AgentGuard-protected version ├── benchmarks/ # Attack evaluation harness + datasets │ ├── dataset/ # 1,200 adversarial + 5,000 benign messages │ └── evaluate.py # Scoring script ├── tests/ │ ├── test_inspector.py │ ├── test_trust.py │ ├── test_capability.py │ └── test_integration.py ├── .pre-commit-config.yaml ├── pyproject.toml ├── README.md └── Dockerfile

4. Installation Guide — Zero to Running in 30 Minutes

Follow these steps exactly in order. Each step has a verification command so you know it worked before moving on. Estimated total time: 25-35 minutes depending on your internet speed.

Before you start — check your operating system These instructions cover macOS and Linux (Ubuntu/Debian). Windows users: install WSL2 first (Windows Subsystem for Linux), then follow the Linux path inside WSL2. All commands run in your terminal.

Step 1 — Install VS Code (IDE)

1. Go to https://code.visualstudio.com and download the installer for your OS.

2. Run the installer.

3. Install the Python extension: open VS Code, press Cmd+Shift+X (Mac) or Ctrl+Shift+X (Linux), search 'Python', install the Microsoft Python extension.

4. Install the Ruff extension: same extension panel, search 'Ruff', install the Astral Software Ruff extension.

# Verify VS Code installed (run from terminal) code --version # Expected: a 1.x version string

Step 2 — Install pyenv (Python version manager)

pyenv lets you install exactly Python 3.11 without affecting your system Python.

macOS:

# Install Homebrew if not already installed /bin/bash -c "$(curl -fsSL https://raw.githubusercontent.com/Homebrew/install/HEAD/install.sh)" # Install pyenv brew install pyenv # Add to your shell profile (~/.zshrc or ~/.bash_profile) echo 'export PYENV_ROOT="$HOME/.pyenv"' >> ~/.zshrc echo 'command -v pyenv >/dev/null || export PATH="$PYENV_ROOT/bin:$PATH"' >> ~/.zshrc echo 'eval "$(pyenv init -)"' >> ~/.zshrc # Reload your shell source ~/.zshrc

Linux (Ubuntu/Debian):

# Install dependencies sudo apt-get update sudo apt-get install -y make build-essential libssl-dev zlib1g-dev \ libbz2-dev libreadline-dev libsqlite3-dev wget curl llvm \ libncursesw5-dev xz-utils tk-dev libxml2-dev libxmlsec1-dev libffi-dev liblzma-dev # Install pyenv curl https://pyenv.run | bash # Add to ~/.bashrc echo 'export PYENV_ROOT="$HOME/.pyenv"' >> ~/.bashrc echo 'command -v pyenv >/dev/null || export PATH="$PYENV_ROOT/bin:$PATH"' >> ~/.bashrc echo 'eval "$(pyenv init -)"' >> ~/.bashrc source ~/.bashrc

Verify:

pyenv --version # Expected: pyenv 2.x.x

Step 3 — Install Python 3.11

# Install Python 3.11.9 (latest 3.11 patch) pyenv install 3.11.9 # Verify pyenv versions # You should see 3.11.9 in the list

Step 4 — Install Poetry (package manager)

# Install Poetry (official installer — do NOT use pip install poetry) curl -sSL https://install.python-poetry.org | python3 - # Add Poetry to your PATH echo 'export PATH="$HOME/.local/bin:$PATH"' >> ~/.zshrc # macOS echo 'export PATH="$HOME/.local/bin:$PATH"' >> ~/.bashrc # Linux source ~/.zshrc # or source ~/.bashrc # Verify poetry --version # Expected: Poetry (version 1.8.x or 2.x.x) # Configure Poetry to create virtualenvs inside the project folder # (makes it easier to point VS Code at the right Python) poetry config virtualenvs.in-project true

Step 5 — Install Claude Code (terminal agent)

Claude Code is Anthropic's terminal coding agent. It requires Claude Pro or Max. If you have upgraded to Pro, install it now.

# Claude Code requires Node.js 18+. Check first: node --version # If Node not installed: # macOS: brew install node # Linux: sudo apt-get install -y nodejs npm # Install Claude Code globally npm install -g @anthropic-ai/claude-code # Verify claude --version # Authenticate (opens browser for OAuth) claude login

Step 6 — Create the AgentGuard project

This creates the full project scaffold using Poetry with Python 3.11.

# Create project directory and initialise with Poetry mkdir agentguard && cd agentguard # Tell pyenv to use 3.11.9 in this directory pyenv local 3.11.9 # Verify Python version python --version # Must show: Python 3.11.9 # Initialise Poetry project poetry init \ --name agentguard \ --description 'Inter-agent security firewall for multi-agent AI systems' \ --author 'Your Name <your@email.com>' \ --python '>=3.11,<3.13' \ --license Apache-2.0 \ --no-interaction

Step 7 — Install all dependencies

Copy the following commands exactly. They install every dependency the project needs.

# Core agent frameworks poetry add langgraph>=0.2 crewai>=0.70 pyautogen>=0.4 # Security & crypto poetry add pynacl>=1.5 pyahocorasick>=2.0 jsonschema>=4.0 PyYAML>=6.0 # ML inference stack (no PyTorch required at runtime) poetry add onnxruntime>=1.17 sentence-transformers>=2.7 numpy>=1.26 # Logging poetry add structlog>=24.0 # Dev dependencies poetry add --group dev pytest>=8.0 pytest-asyncio>=0.23 pytest-cov>=5.0 poetry add --group dev hypothesis>=6.0 ruff>=0.4 mypy>=1.9 pre-commit>=3.7 # Optional: OpenTelemetry SIEM export poetry add --optional opentelemetry-sdk opentelemetry-exporter-otlp # Verify the virtual environment was created poetry env info # Should show Python 3.11.x and a .venv path inside your project

Step 8 — Create the folder structure

# Create all directories mkdir -p agentguard/{inspector,trust,capability,adapters,mcp,audit} mkdir -p schemas manifests examples/{vulnerable_pipeline,secured_pipeline} mkdir -p benchmarks/dataset tests # Create __init__.py files touch agentguard/__init__.py touch agentguard/{inspector,trust,capability,adapters,mcp,audit}/__init__.py # Create placeholder source files touch agentguard/firewall.py touch agentguard/inspector/{rule_filter,ml_scorer,consistency}.py touch agentguard/trust/{authority,signing}.py touch agentguard/capability/{manifest,enforcer}.py touch agentguard/adapters/{langgraph,crewai,autogen}.py touch agentguard/mcp/output_inspector.py touch agentguard/audit/{logger,otel}.py touch tests/{test_inspector,test_trust,test_capability,test_integration}.py touch README.md Dockerfile .gitignore # Verify structure find . -type f -name '*.py' | head -20

Step 9 — Configure Ruff and pre-commit

Add the following to your pyproject.toml to configure Ruff:

# Add to pyproject.toml [tool.ruff] line-length = 100 target-version = 'py311' select = ['E', 'F', 'W', 'I', 'N', 'UP', 'S'] ignore = ['S101'] # Allow assert in tests [tool.ruff.per-file-ignores] 'tests/*' = ['S', 'E501'] [tool.mypy] python_version = '3.11' strict = true ignore_missing_imports = true [tool.pytest.ini_options] asyncio_mode = 'auto' testpaths = ['tests'] addopts = '--cov=agentguard --cov-report=term-missing --cov-fail-under=85'

Create the pre-commit configuration:

# .pre-commit-config.yaml repos: - repo: https://github.com/astral-sh/ruff-pre-commit rev: v0.4.0 hooks: - id: ruff args: [--fix] - id: ruff-format - repo: https://github.com/pre-commit/mirrors-mypy rev: v1.9.0 hooks: - id: mypy additional_dependencies: [types-PyYAML, types-jsonschema]

# Install pre-commit hooks poetry run pre-commit install # Run once to verify poetry run pre-commit run --all-files # Expected: all checks pass (or only formatting fixes on empty files)

Step 10 — Configure linting and pre-commit

Use .pre-commit-config.yaml and pyproject.toml ([tool.ruff], [tool.mypy]) so every contributor gets the same checks (Ruff, mypy, pytest) regardless of editor. See CONTRIBUTING.md for security conventions (PyNaCl for signing, no payload logging).

Step 11 — Initialise Git and GitHub

# Initialise git git init git branch -M main # Create .gitignore cat > .gitignore << 'EOF' .venv/ __pycache__/ *.pyc .pytest_cache/ .mypy_cache/ .ruff_cache/ *.egg-info/ dist/ *.onnx # Do NOT commit the model — too large benchmarks/dataset/*.jsonl # Dataset generated, not committed audit.jsonl EOF # Initial commit git add . git commit -m 'chore: initialise AgentGuard project scaffold' # Create GitHub repo (install gh CLI first: brew install gh / sudo apt install gh) gh repo create agentguard --public --description 'Inter-agent security firewall for multi-agent AI systems' git remote add origin https://github.com/YOUR_USERNAME/agentguard.git git push -u origin main

Step 12 — Verify the full environment

Run this complete verification check. Every command should succeed.

# 1. Python version poetry run python --version # Must show: Python 3.11.9 # 2. All packages importable poetry run python -c " import langgraph, crewai, autogen import nacl.signing import ahocorasick import jsonschema import onnxruntime import sentence_transformers import structlog print('All imports successful')" # 3. Test suite runs (no tests yet, but framework should work) poetry run pytest --co -q # Expected: 0 tests collected (no errors) # 4. Ruff passes on empty files poetry run ruff check agentguard/ # Expected: All checks passed # 5. Claude Code connected claude --version # 6. Git status clean git status # Expected: nothing to commit, working tree clean

You are ready to build If all 6 checks above pass, your development environment is fully configured. The next step is writing the vulnerable reference pipeline — the 3-agent system that demonstrates the attacks AgentGuard will defend against.

5. 3-Week Build Schedule

Week	Daily focus	Exit criterion
Week 1 Days 1-2	Dev environment + vulnerable pipeline. 3-agent LangGraph system that demonstrates indirect injection, propagation, and capability escalation.	Attacks reproducible. Baseline attack success rate measured at 100%.
Week 1 Days 3-5	Rule-based pre-filter. Aho-Corasick pattern engine with 50+ injection signatures. LangGraph adapter v1.	Rule filter alone blocks 40%+ of baseline attacks. LangGraph wrap works end-to-end.
Week 2 Days 1-3	DeBERTa fine-tuning on Kaggle GPU. Dataset prep from InjectAgent + MASpi. ONNX export and integration into ml_scorer.py.	ML scorer alone achieves >80% detection. Inference <15ms CPU verified.
Week 2 Days 4-5	Trust verifier: Ed25519 keypair generation, Trust Authority sidecar, signing/verification in message envelope.	Impersonation attack: 100% blocked. Per-run key rotation verified.
Week 3 Days 1-2	Capability manifest enforcer. YAML schema, runtime enforcement, monotonic attenuation. CrewAI and AutoGen adapters.	Capability escalation: 100% blocked. All three framework adapters tested.
Week 3 Days 3-4	Benchmark dataset: 1,200 adversarial inter-agent messages generated via Claude API batch. Evaluation harness. Results measured.	Benchmark dataset published on Hugging Face. Full results table generated.
Week 3 Day 5	GitHub v1.0 release: clean README, quick-start guide, demo video script, PyPI publish, blog post first draft.	pip install agentguard works. GitHub repo public. Blog post ready to publish.

6. How to Work With Claude Through the Build

Claude (Sonnet 4.6, Claude Pro) can generate every module in this project. Here is exactly what to expect and how to work effectively.

6.1 What Claude generates directly

• Complete Python modules from a spec — paste the function signature and docstring, get the full implementation

• Test files: pytest fixtures, attack scenario tests, integration tests for each adapter

• The benchmark dataset: 1,200 adversarial inter-agent messages across 5 attack classes via Claude API batch

• YAML capability manifests for all example agents

• GitHub Actions workflow files, Dockerfile, pyproject.toml

• README, technical blog post draft, benchmark results writeup

• Debug assistance: paste a stack trace, get the fix and an explanation

6.2 Daily workflow that works

5. Start each session by telling Claude exactly which file you are working on and what it needs to do.

6. Paste errors back exactly as they appear — do not paraphrase. Claude needs the full stack trace.

7. After each module is written, run pytest immediately. Paste failures back.

8. Use Claude Code in the terminal for generating entire new modules. Use the editor for editing existing files.

9. At the end of each day, commit what works. Do not carry uncommitted work overnight.

6.3 Where to use the Claude API separately

The benchmark dataset generation requires Claude API calls outside of this chat — you need to generate 1,200 adversarial messages programmatically. Use the Batch API for this to keep costs under $10.

# Install the Anthropic SDK for the benchmark generation script poetry add anthropic --group dev # Set your API key (get from console.anthropic.com) export ANTHROPIC_API_KEY=sk-ant-... # The benchmark generation script (benchmarks/generate_dataset.py) # will be written in Week 3 Day 3 of the build. # It uses the Batch API at $1.50/MTok (50% off standard Sonnet rate) # to generate 1,200 adversarial messages for roughly $5-8 total.

7. Total Cost Summary

Item	Cost (GBP estimated)
Claude Pro subscription (1 month)	~£16
Anthropic API — benchmark dataset generation via Batch API	~£6–12
Kaggle GPU for DeBERTa fine-tuning	£0 (free tier, 30 hrs/week)
OR Google Colab Pro (optional, faster GPUs)	~£10
Cloud spot instance for benchmark evaluation runs (optional)	£3–7
VS Code	£0
Claude Code	£0 (included in Claude Pro)
GitHub, PyPI, Docker Hub accounts	£0
Total — minimum	~£22
Total — comfortable (with Colab Pro + cloud compute)	~£45

The most important spend Claude Pro at £16/month is the single most impactful cost in this list. Without it, you will hit free tier message limits (15-40 messages per 5-hour window) within the first hour of a serious coding session. Upgrade before starting Day 1.

8. Quick Reference

8.1 Daily commands

# Activate the Poetry environment (run once per terminal session) poetry shell # Run all tests poetry run pytest # Run tests with verbose output poetry run pytest -v # Run only a specific test file poetry run pytest tests/test_inspector.py # Check linting poetry run ruff check agentguard/ # Auto-fix linting poetry run ruff check --fix agentguard/ # Type checking poetry run mypy agentguard/ # Add a new dependency poetry add package-name # Start Claude Code in terminal claude # Open VS Code in current directory code .

8.2 Troubleshooting common setup issues

Issue	Fix
poetry: command not found	Run: export PATH="$HOME/.local/bin:$PATH" and reload your shell. Check that the Poetry installer completed without errors.
python --version shows 3.9 or 3.10 instead of 3.11	Run pyenv local 3.11.9 inside the project folder. Check that pyenv init is in your shell profile and the profile was reloaded.
import langgraph fails after poetry add	Run poetry shell first to activate the virtual environment, then try the import. The packages are installed in the .venv folder, not your system Python.
PyNaCl install fails on Linux	Run: sudo apt-get install -y libsodium-dev then retry poetry add pynacl.
pyahocorasick install fails on macOS	Run: brew install automake then retry. The package needs C build tools.
sentence-transformers install is slow	It pulls a 80MB model on first use. Normal. Let it complete.
Claude Code: authentication error	Run claude login again. The OAuth token expires after 30 days.
VS Code can't find Python interpreter	Open VS Code, press Cmd+Shift+P, type 'Python: Select Interpreter', choose the .venv/bin/python inside your project folder.

8.3 Key URLs

Resource	URL
VS Code download	https://code.visualstudio.com
Claude Code docs	https://docs.anthropic.com/en/docs/claude-code
Anthropic API console (for API key)	https://console.anthropic.com
Kaggle (free GPU for fine-tuning)	https://www.kaggle.com/code
pyenv installation guide	https://github.com/pyenv/pyenv#installation
Poetry documentation	https://python-poetry.org/docs
LangGraph documentation	https://langchain-ai.github.io/langgraph
DeBERTa-v3-small on Hugging Face	https://huggingface.co/microsoft/deberta-v3-small
OWASP Agentic Security Initiative Top 10	https://owasp.org/www-project-top-10-for-large-language-model-applications
InjectAgent benchmark dataset	https://huggingface.co/datasets/sunblaze-edgecloud/InjectAgent

AgentGuard Design Document & Setup Guide v1.0 — June 2026 — Confidential