CrewAI

Pavri integrates with CrewAI through a before-tool-call hook that enforces runtime governance policies on every tool execution across all crews in the process.

One-Line Integration

from pavri import PavriConfig, secure

crew = build_crewai_crew()
crew = secure(crew, PavriConfig(agent_name="ops-crew", plugin="crewai"))

The secure() call attaches the Pavri runtime to the crew, registers it with the backend, and installs the enforcement hook.

Supported Versions

• CrewAI >=0.80.0
• Python >=3.12

How It Works

Plugin Detection

The CrewAIAdapter matches when either:

• You pass plugin="crewai" in the config
• The target object's module name contains "crewai"

Hooks Attached

When the runtime has an active policy cache and telemetry emitter, secure() registers a global before-tool-call hook:

Hook	Purpose
_pavri_before_tool	Evaluates policy before tool execution; returns True to allow, False to block

Before-Tool Enforcement

The hook follows CrewAI's register_before_tool_call_hook convention. It receives a ToolCallHookContext and returns a boolean:

# Internal flow — you do not call this directly
def _pavri_before_tool(hook_ctx):
    tool_name = hook_ctx.tool_name
    # Evaluates enforce_policy(f"tool:{tool_name}", ctx)
    # Returns True to allow, False to block

The hook extracts tool_name from the hook context and evaluates the policy:

• On allow: Returns True — the tool executes normally.
• On deny: Catches the PolicyDeniedError internally and returns False — CrewAI skips the tool execution.

Policy evaluation respects the configured fail_mode:

• fail-open (default): If policy evaluation fails, the tool call is allowed.
• fail-closed: If policy evaluation fails, the tool call is blocked.

Global Hook Scope

CrewAI's register_before_tool_call_hook is global — it affects all crews in the Python process. If you run multiple crews, the Pavri hook applies to all of them. The ToolCallHookContext.crew reference can be used to scope enforcement by crew instance in future releases.

If CrewAI is not installed, the hook is stored as an attribute on the target object (_pavri_before_tool) for testing and inspection.

Configuration

Key PavriConfig options for CrewAI:

from pavri import PavriConfig

config = PavriConfig(
    agent_name="ops-crew",
    plugin="crewai",
    api_key="fab_...",
    backend_url="https://pavri.example.com",
    org_id="org-acme",
    session_id="session-123",
    team="platform",
    environment="production",
    fail_mode="open",
)

Field	Default	Description
fail_mode	"open"	Whether to allow or deny when policy evaluation fails
telemetry_mode	"full"	Controls telemetry detail level
environment	"development"	Deployment environment tag
policy_sync.poll_interval_seconds	60	How often to poll for policy updates

CrewAI Security Notes

CrewAI has built-in security features that Pavri complements:

• Code execution sandboxing: CrewAI defaults to code_execution_mode: "safe" (Docker). Pavri does not currently detect or alert on unsafe_mode, but this is planned for a future release.
• Task-level guardrails: CrewAI supports function-based and LLM-based guardrails per task. Pavri adds cross-task, cross-crew policy enforcement.
• Rate limiting: CrewAI has crew-level max_rpm. Pavri adds per-tool and budget-based limits.

Graceful Degradation

If the Pavri runtime cannot build an enforcement context, the plugin skips hook installation entirely. The crew runs without Pavri enforcement. Check the runtime status to verify:

from pavri.core import get_runtime

runtime = get_runtime(crew)
status = runtime.status()
print(status.connected, status.policy_revision)

Troubleshooting

Crew runs but no policy enforcement

• Verify the backend is reachable and api_key is set.
• Check runtime.status().policy_revision — if 0, the SDK has no cached policy.
• The plugin requires both a policy cache and telemetry emitter.
• If CrewAI is not installed, the hook is stored on the target object but not registered globally. Install CrewAI for production use.

Tool blocked silently

• CrewAI's hook system blocks tools by returning False, which causes CrewAI to skip the tool without raising an exception. Check the Pavri dashboard for policy denial telemetry events to see which tools were blocked and why.

Hook affects all crews

• The before-tool hook is process-global. If you secure one crew, all crews in the process are affected. This is a CrewAI design constraint, not a Pavri limitation.

Plugin not detected

• Pass plugin="crewai" explicitly in the config.
• Ensure the crew object's module includes "crewai" in its path for auto-detection.

What's Deferred

The following capabilities are planned for Phase 2:

• Log forwarding from the CrewAI plugin
• After-tool-call hook for result inspection and telemetry
• Trace-link capture (via AgentOps or Langtrace OTel integration)
• Per-crew hook scoping in multi-crew processes
• Unsafe mode detection and alerting
• Delegation monitoring via event bus patterns
• Crew lifecycle hook integration (before/after kickoff)