DS DevShelfHub Projects · AI tools
Tutorials / CrewAI / Reference / Decorators / @before_llm_call_crew
Decorator crewai.hooks

@before_llm_call_crew: Reference Guide

By DevShelfHub

Runs before every LLM call within the crew — modify the prompt, log, gate, or replace the request.

See the CrewAI API reference index, CrewAI introduction, hooks and events tutorial, and core concepts for surrounding context.

What is @before_llm_call_crew?

Register a plain function (or stack multiple registrations carefully) to intercept each LLM invocation before tokens leave your process. The framework passes an LLMCallHookContext with fields such as prompt, model name, agent metadata, and tool context so you can redact regulated data, prepend compliance preambles, enforce spend caps, or swap models for cheaper tiers on classification-shaped prompts.

Returning False short-circuits the call entirely — use sparingly for kill switches, not routine control flow. Returning None leaves the call untouched aside from any in-place mutations you applied to the context object. Because hooks are global per process unless namespaced by CrewAI APIs in your version, tests must clear registrations between cases to avoid cross-test leakage.

Pair with @after_llm_call_crew for symmetric response handling, and prefer Task.guardrail when validation belongs to a single task rather than every model call in the crew.

When to Use

Prompt augmentation, cost gating, content filtering.

Use Cases

  • • Cost limits
  • • Prompt augmentation
  • • PII redaction

Key Features

  • ✓ Crew-scoped
  • ✓ Receives LLMCallHookContext
  • ✓ Can short-circuit the call

When NOT to Use

One-off transformations — do them inline in the task description.

Notes

Latency and retries

Hooks run on the critical path for every completion. Keep CPU work tiny; push enrichment offline. Remember LLM providers already retry — avoid doubling retries inside hooks.

Mutating prompts

Never assign None to prompt by mistake. If you need to block, return False explicitly instead of leaving an empty string that still incurs billing.

Version drift

Context attributes expand frequently. Use getattr with defaults and monitor release notes when upgrading CrewAI.

Import

python 
from crewai.hooks import before_llm_call_crew

How to Apply

python 
@before_llm_call_crew
def gate(ctx):
    if too_expensive(ctx): return False

What It Enables

  • ✓ Prompt-time guardrails
  • ✓ Cost and content gates

Code Examples

Redact PII

python 
@before_llm_call_crew
def redact(ctx):
    ctx.prompt = scrub(ctx.prompt)

Hard cap on expensive models

python 
@before_llm_call_crew
def cap(ctx):
    if ctx.model and 'gpt-4' in ctx.model and not ctx.prompt:
        return False
    return None

Structured telemetry

python 
@before_llm_call_crew
def emit(ctx):
    tracer.add_event('llm.request', model=ctx.model, agent=getattr(ctx, 'agent', None))
    return None

Integration Patterns

Pairs with @after_llm_call_crew
Use clear_all_global_hooks() in tests

Common Mistakes

❌ Mutating ctx.prompt to None

✅ Return a new string or leave the field set to a non-empty value.

Related: Task class reference, Agent class reference, and the first Crew tutorial.

@before_llm_call_crew FAQ

What is @before_llm_call_crew in CrewAI?

Runs before every LLM call within the crew — modify the prompt, log, gate, or replace the request. Register a plain function (or stack multiple registrations carefully) to intercept each LLM invocation before tokens leave your process. The framework passes an LLMCallHookContext with fields such as prompt, model name, agent metadata, and tool context so you can redact regulated data, prepend compliance preambles, enforce spend caps, or swap models for cheaper tiers on classification-shaped prompts. Returning False short-circuits the call entirely — use sparingly for kill s…

Which module defines the CrewAI decorator @before_llm_call_crew?

DevShelfHub maps @before_llm_call_crew to Python module crewai.hooks. Pin your installed crewai version and match imports to the import snippet on this page.

When should I use @before_llm_call_crew?

Prompt augmentation, cost gating, content filtering.

When should I avoid @before_llm_call_crew?

One-off transformations — do them inline in the task description.

How do I apply @before_llm_call_crew in Python?

@before_llm_call_crew def gate(ctx): if too_expensive(ctx): return False

Where can I explore more CrewAI API reference pages?

Open the CrewAI API reference index on DevShelfHub to search classes, methods, and decorators, each with runnable examples, parameters, common mistakes, and cross-links.