Agent Guardrails Cookbook

Open-source, MIT-licensed, runnable recipes that guard AI agents against prompt injection, jailbreaks, data exfiltration, PII leaks and unsafe tool use, at every checkpoint, in any framework, through MCP or API. Clone it with git clone https://github.com/ProofAgent-ai/agent-guardrails-cookbook.

Three checkpoints, four checks

• 1 · Input: the user message. Direct injection, jailbreaks, PII (OWASP LLM01, LLM02).
• 2a · Tool call: what the agent wants to do. Excessive agency, data sent out (LLM06).
• 2b · Tool result: pages, files, emails and API responses. Indirect prompt injection (LLM01).
• 3 · Output: the reply. PII leaks, system-prompt leaks (LLM02, LLM07).

Recipes for every agent framework

• Plain Python, the reference implementation, runs offline.
• LangGraph: guard nodes, MCP and hybrid.
• OpenAI Agents SDK: tool_input_guardrail and tool_output_guardrail.
• CrewAI: before_tool_call and after_tool_call.
• Claude Agent SDK: PreToolUse and PostToolUse hooks.
• n8n: a guarded-tool sub-workflow.

MCP or API: three ways to wire it

API guard nodes call POST /v1/scan at every step. MCP puts check_user_message and the check_* tools inside the agent. The hybrid, recommended for production, puts an API gateway in front of the agent and lets the agent check its tool calls, tool results and reply over MCP. In every pattern the code decides to check, not the model.

Quick start

Clone the repository and run python3 recipes/00-plain-python/agent.py --unguarded to watch the attacks succeed, then run it again without the flag to see them blocked, offline and with no key. Add a free ProofAgent Nano key from app.proofagent.ai for production-grade detection: 134 PII types, 41 AI risks, English, French and Arabic.

View the cookbook on GitHub Try the live demo

What is the Agent Guardrails Cookbook?

An open-source, MIT-licensed set of runnable recipes that show how to guard AI agents against prompt injection, jailbreaks, data exfiltration, PII leaks and unsafe tool use. Every recipe checks the same four places where untrusted text enters an agent: the user input, the tool call, the tool result and the reply.

Which agent frameworks does it cover?

Plain Python, LangGraph, the OpenAI Agents SDK, CrewAI, the Claude Agent SDK and n8n. Each recipe uses the framework's own hooks, such as tool_input_guardrail in the OpenAI Agents SDK, before_tool_call in CrewAI and PreToolUse in the Claude Agent SDK.

Should I call a guardrail over MCP or over an API?

Both work, and the cookbook shows three wirings: API guard nodes, MCP checks inside the agent, and a hybrid. The hybrid is recommended for production: an API gateway checks every user message before the agent sees it, and the agent checks its own tool calls, tool results and reply over MCP. In every pattern your code decides to check, not the model.

Do I need an API key to run it?

No. Every recipe runs offline with a built-in local guard and a stub model, so anyone can learn from it in about a minute. For production-grade detection, a free ProofAgent Nano key from app.proofagent.ai adds 134 PII types, 41 AI risks, English, French and Arabic, and regulation mapping.

Which standards do the recipes map to?

The checkpoints map to the OWASP Top 10 for LLM Applications (LLM01 prompt injection, LLM02 sensitive information disclosure, LLM06 excessive agency, LLM07 system prompt leakage) and to MITRE ATLAS. The references also cover NIST AI 600-1 and Article 15 of the EU AI Act.

How do I test my own agent against attacks?

Run the attack corpus in attacks/corpus.jsonl, which holds labelled direct and indirect injections, jailbreaks, PII, exfiltration and unsafe tool calls in English, French and Arabic. The playground runs any recipe end to end with any guard and any model, including local models in LM Studio or Ollama, and animates every checkpoint.