crewai-governance

Runtime governance middleware for CrewAI. Three features, one pip install, zero config.

What it does

Install

pip install crewai-governance

Usage

from crewai import Agent, Task, Crew, Process
from crewai.project import CrewBase, before_kickoff, after_kickoff
from crewai_governance import governance_before_kickoff, governance_after_kickoff

@CrewBase
class ResearchCrew:
    @before_kickoff
    def before(self, inputs):
        return governance_before_kickoff(
            crew_name="research_crew",
            mandate="research AI governance papers"
        )(inputs)

    @after_kickoff
    def after(self, result):
        return governance_after_kickoff("research_crew")(result)

    # ... your agents, tasks, crew as normal

That's it. Two lines added to your existing crew class.

What happens

First run: Overlap detection finds nothing. No prior reports to inherit. Your crew runs normally. After completion, an exit report is written to .crewai-governance/exit_reports/.

Second run: Before kickoff, the middleware injects a summary of the first run's findings into the crew's context. Your agents now know what was already tried. After completion, another exit report is written.

Parallel runs: If two crews are running with overlapping mandates, overlap detection warns you before the second one starts.

Exit report structure

{
  "reportId": "research_crew-1724012345678",
  "crewName": "research_crew",
  "completedAt": "2026-08-20T15:00:00Z",
  "rawOutput": "Found 3 papers on multi-agent governance...",
  "tasksOutput": [
    {
      "description": "Search for recent papers",
      "raw": "Found papers by Smith (2026), Lee (2025)...",
      "agent": "researcher"
    },
    {
      "description": "Summarize findings",
      "raw": "Key themes: coordination failures, trust...",
      "agent": "writer"
    }
  ],
  "tokenUsage": {"total_tokens": 2500},
  "mandateCompleted": true
}

Configuration

from crewai_governance import GovernanceConfig

config = GovernanceConfig(
    storage_dir=".crewai-governance",       # where data lives
    max_inheritance_reports=5,              # how many prior reports to inject
    enable_overlap_detection=True,          # turn overlap checking on/off
    enable_inheritance=True,                # turn inheritance on/off
)

# Pass config to hooks
governance_before_kickoff("my_crew", "my mandate", config)(inputs)
governance_after_kickoff("my_crew", config)(result)

Why this exists

Multi-agent coordination failures account for 37% of all multi-agent system failures (MAST Failure Taxonomy). The top failure modes -- infinite handoff loops, context loss, false consensus -- happen because agents have no memory of what came before and no awareness of what's running alongside them.

This package is the smallest possible intervention: give agents a record of past runs, warn when work overlaps, and let new runs learn from old ones.

License

MIT