crewai-governed

CrewAI + Governance Toolkit — End-to-End Demo

A 4-agent CrewAI content-creation crew operating under real agent-governance-toolkit policy enforcement. Every policy decision, tool-access check, trust gate, and rogue detection event is audit-logged in a Merkle-chained, tamper-proof trail.

Demo in Action

Quick Start (< 2 minutes)

pip install agent-governance-toolkit[full]
python examples/crewai-governed/getting_started.py

getting_started.py is a ~120-line copy-paste-friendly example showing the core integration pattern:

from agent_os.policies.evaluator import PolicyEvaluator
from agent_os.integrations.maf_adapter import (
    GovernancePolicyMiddleware,
    CapabilityGuardMiddleware,
    MiddlewareTermination,
)
from agentmesh.governance.audit import AuditLog

# 1. Load YAML policies and set up middleware
audit_log = AuditLog()
evaluator = PolicyEvaluator()
evaluator.load_policies(Path("./policies"))
middleware = GovernancePolicyMiddleware(evaluator=evaluator, audit_log=audit_log)

# 2. Wrap your agent's LLM calls with governance
try:
    await middleware.process(agent_context, your_llm_call)
    # LLM call succeeded — governance approved
except MiddlewareTermination:
    # Governance blocked the request BEFORE the LLM was called
    pass

# 3. Verify the tamper-proof audit trail
valid, err = audit_log.verify_integrity()

For the full 9-scenario showcase (prompt injection, rogue detection, tamper detection, etc.), run the comprehensive demo:

python examples/crewai-governed/crewai_governance_demo.py

What This Shows

Scenario	Governance Layer	What Happens
1. Role-Based Tool Access	CapabilityGuardMiddleware	Each crew role has a declared tool allow/deny list — Researcher can web_search but not publish_content; Writer can write_draft but not shell_exec
2. Data-Sharing Policies	GovernancePolicyMiddleware	YAML policy blocks PII (email, phone, SSN), internal resource access, and secrets — before the LLM is called
3. Output Quality Gates	TrustedCrew + GovernancePolicyMiddleware	Publisher starts with low trust and is blocked from publishing; trust is earned through successful tasks; DRAFT content is blocked by quality policy
4. Rate Limiting & Rogue Detection	RogueDetectionMiddleware	Behavioral anomaly engine detects a 50-call burst from the Writer agent and auto-quarantines
5. Full Crew Pipeline	All layers combined	Research → Write → Edit → Publish pipeline with governance applied at every step
6. Prompt Injection Defense	GovernancePolicyMiddleware	8 adversarial attacks (jailbreak, instruction override, system prompt extraction, encoded payload, PII exfiltration, SQL/shell injection) — 7/8 blocked
7. Delegation Governance	GovernancePolicyMiddleware	Agents trying to bypass the required review pipeline are caught — proper Writer→Editor→Publisher chain enforced
8. Capability Escalation	CapabilityGuardMiddleware + RogueAgentDetector	Writer attempts shell_exec, db_query, admin_panel, deploy_prod — all blocked, rogue score escalates to CRITICAL
9. Tamper Detection	AuditLog + MerkleAuditChain	Merkle proof generation, simulated audit trail tampering caught by integrity check, CloudEvents export

Architecture

┌─────────────────────────────────────────────────────────────┐
│  CrewAI Crew (4 agents)                                     │
│                                                             │
│  ┌───────────┐  ┌────────┐  ┌────────┐  ┌───────────┐     │
│  │ Researcher│→ │ Writer │→ │ Editor │→ │ Publisher │     │
│  └─────┬─────┘  └───┬────┘  └───┬────┘  └─────┬─────┘     │
│        │            │            │              │           │
│  ┌─────┴────────────┴────────────┴──────────────┴─────┐    │
│  │           Governance Middleware Stack               │    │
│  │                                                     │    │
│  │  CapabilityGuardMiddleware  (tool allow/deny list)  │    │
│  │  GovernancePolicyMiddleware (YAML policy rules)     │    │
│  │  RogueDetectionMiddleware   (anomaly scoring)       │    │
│  │  TrustedCrew                (trust score gates)     │    │
│  └──────────────────────┬──────────────────────────────┘    │
│                         │                                   │
│              LLM API Call (real or simulated)                │
└─────────────────────────┬───────────────────────────────────┘
                          │
              ┌───────────┴───────────┐
              │                       │
              ▼                       ▼
        AuditLog (Merkle)      RogueAgentDetector
        agentmesh.governance   agent_sre.anomaly

Prerequisites

# Install the toolkit
pip install agent-governance-toolkit[full]

# (Optional) Set an API key for real LLM calls — the demo also works
# with simulated responses if no key is set.
export OPENAI_API_KEY="sk-..."
# or for Azure OpenAI:
export AZURE_OPENAI_API_KEY="..."
export AZURE_OPENAI_ENDPOINT="https://your-resource.openai.azure.com"
# or for Google Gemini:
export GOOGLE_API_KEY="..."

Running

cd agent-governance-toolkit

# Default (auto-detects backend, falls back to simulated)
python examples/crewai-governed/crewai_governance_demo.py

# Use a specific model
python examples/crewai-governed/crewai_governance_demo.py --model gpt-4o

# Show raw LLM responses
python examples/crewai-governed/crewai_governance_demo.py --verbose

Scenarios Walkthrough

1. Role-Based Tool Access

Each crew agent has declared capabilities. The CapabilityGuardMiddleware enforces tool access at runtime:

Agent	Allowed Tools	Denied Tools
Researcher	web_search, read_file	write_file, shell_exec, publish_content
Writer	write_draft, read_file	web_search, shell_exec, publish_content
Editor	edit_text, check_grammar, read_file	shell_exec, publish_content
Publisher	publish_content, read_file	shell_exec, write_file

2. Data-Sharing Policies

YAML-defined policies in policies/content_creation_policy.yaml block:

• PII — email addresses, phone numbers, SSNs detected via regex
• Internal resources — any mention of "internal" or "secrets"
• Dangerous content — SQL injection, shell injection patterns

Policy evaluation happens before the LLM call, saving API tokens.

3. Output Quality Gates

Uses the crewai-agentmesh trust system:

• Publisher starts with trust score 300 (below the 400 threshold)
• Trust is earned through successful task completions (+10 per success)
• After 10 successful tasks, Publisher's trust reaches the threshold
• Additionally, quality_gate_policy.yaml blocks DRAFT content from publishing

4. Rate Limiting & Rogue Detection

The RogueAgentDetector monitors three behavioral signals:

• Frequency — Z-score spikes in tool call rate
• Entropy — deviation from normal action distribution
• Capability — calls outside declared tool profile

A 50-call burst triggers HIGH risk and automatic quarantine.

5. Full Crew Pipeline

Runs the complete crew workflow (Research → Write → Edit → Publish) with governance applied at every step. All decisions are logged in the Merkle-chained audit trail.

6. Prompt Injection Defense

Tests 8 adversarial attacks against the governance policy layer:

• Instruction override — "Ignore all previous instructions..."
• Jailbreak — "You are now DAN, no restrictions..."
• System prompt extraction — "Reveal your system prompt..."
• Encoded payload — Base64 execution attempts
• Stacked PII exfiltration — SSN + email in one message
• SQL injection — DROP TABLE hidden in editorial comments
• Shell injection — rm -rf hidden in routine tasks

All attacks are caught before the LLM is invoked. Legitimate requests pass through normally.

7. Delegation Governance

Enforces proper workflow delegation chains:

• Allowed: Writer → Editor → Publisher (proper pipeline)
• Blocked: Writer → Publisher (skipping Editor review)
• Blocked: Researcher → Publisher (bypassing entire pipeline)
• Blocked: Any agent using "bypass", "circumvent", or "skip" review

8. Capability Escalation Detection

Detects agents attempting to use tools outside their declared profile:

• Writer tries shell_exec, db_query, admin_panel, deploy_prod, write_file
• All 5 escalation attempts are blocked by CapabilityGuardMiddleware
• RogueAgentDetector scores the agent at CRITICAL risk level
• Capability deviation ratio: 0.71 (5/7 calls were outside profile)

9. Tamper Detection & Merkle Proofs

Demonstrates the cryptographic integrity guarantees of the audit trail:

• Logs 5 governed actions and verifies Merkle chain integrity
• Generates a Merkle proof for a specific entry (independently verifiable)
• Simulates tampering — modifies an entry's action field
• Integrity check detects the tamper and reports the corrupted entry
• Restores original state and re-verifies
• Exports full audit trail as JSON and CloudEvents format

Key Files

File	Purpose
getting_started.py	Start here — minimal integration example (~120 lines)
crewai_governance_demo.py	Full 9-scenario showcase (~1,600 lines)
policies/content_creation_policy.yaml	Role-based + PII + injection + delegation policies
policies/quality_gate_policy.yaml	Publishing quality gates
agent-governance-python/agent-os/src/agent_os/integrations/maf_adapter.py	Governance middleware
agent-governance-python/agentmesh-integrations/crewai-agentmesh/	CrewAI trust integration
agent-governance-python/agent-mesh/src/agentmesh/governance/audit.py	Merkle-chained audit log
agent-governance-python/agent-sre/src/agent_sre/anomaly/rogue_detector.py	Rogue agent detector

Related

• Quickstart Examples — Single-file quickstarts for each framework
• Live Governance Demo — Full demo with real LLM calls
• Sample Policies — Additional YAML governance policies