What is register_before_llm_call_hook()?
`register_before_llm_call_hook(fn)` appends `fn` to the same global registry that backs `@before_llm_call_crew`, which matters when decorators are impossible: dynamically loaded plugins, feature-flagged policies, or notebooks where you cannot decorate a frozen class. The callable receives `LLMCallHookContext` with prompt, model, agent metadata, and usage hints; return a string to replace the prompt, `None` to leave it untouched, or `False` to veto the call entirely.
Because registration is additive and global, ordering is implicit insertion order — mixing decorators and programmatic hooks in one process can surprise teams who assumed lexicographic file order. Document the sequence you rely on and add regression tests that assert redaction still runs before spend caps.
Always pair long-lived processes with a strategy for unloading hooks (`clear_all_global_hooks()` in tests, explicit teardown in workers) so hot reloads and pytest parametrization do not leak policies across cases. When you ship multiple crews in one worker, log hook registration counts at boot so unexpected imports surface before traffic arrives.
Use Cases
- • Plugin systems
- • Conditional hook registration
Key Features
- ✓ Runtime registration
- ✓ Composable
When NOT to Use
Static crew code — the decorator is cleaner.
Notes
Global registry semantics
These APIs mutate process-wide state. A registration in an imported module sticks around until cleared — treat imports as side-effecting configuration.
Latency on the LLM hot path
Before hooks run on every completion-boundary call. Keep work O(1) on prompt size; push heavy enrichment to workers or sampling.
False vs None confusion
Returning False aborts the call; returning an empty string still sends a (possibly blank) prompt downstream. Be explicit in code reviews.
Version drift with decorators
Mixing decorator-based hooks from library A and programmatic hooks from library B can duplicate effort or fight for last-writer-wins. Namespace your registrations and log them at startup.
Parameters
| Parameter | Type | Required | Purpose |
|---|---|---|---|
| fn | Callable[[LLMCallHookContext], Any] | No | The hook callable. |
Code Examples
Register
register_before_llm_call_hook(my_hook)Cost cap from settings
from crewai.hooks import register_before_llm_call_hook
def spend_guard(ctx):
if ctx.usage and ctx.usage.total_tokens > 50_000:
return False
register_before_llm_call_hook(spend_guard)Pytest isolation
import pytest
from crewai.hooks import clear_all_global_hooks, register_before_llm_call_hook
@pytest.fixture(autouse=True)
def _hooks():
clear_all_global_hooks()
register_before_llm_call_hook(lambda ctx: None)
yield
clear_all_global_hooks()When to Use
Plugin systems, runtime-conditional hooks.
Common Mistakes
❌ Registering the same hook twice
✅ Track registrations or reset with clear_all_global_hooks().
Related: @tool decorator reference, Agent class reference, and the first Crew tutorial.
register_before_llm_call_hook() FAQ
What is register_before_llm_call_hook() in CrewAI?
Registers a before-LLM-call hook at runtime — alternative to the @before_llm_call_crew decorator. `register_before_llm_call_hook(fn)` appends `fn` to the same global registry that backs `@before_llm_call_crew`, which matters when decorators are impossible: dynamically loaded plugins, feature-flagged policies, or notebooks where you cannot decorate a frozen class. The callable receives `LLMCallHookContext` with prompt, model, agent metadata, and usage hints; return a string to replace the prompt, `None` to leave it untouched, or `False` to veto the call entirely. Because …
Which CrewAI types expose the method register_before_llm_call_hook()?
DevShelfHub documents register_before_llm_call_hook() on Programmatic hook registration. The reference maps it to Python module crewai.hooks — pin your installed crewai version and match imports to the snippet on this page.
When should I use register_before_llm_call_hook()?
Plugin systems, runtime-conditional hooks.
When should I avoid register_before_llm_call_hook()?
Static crew code — the decorator is cleaner.
How do I call register_before_llm_call_hook() from Python?
register_before_llm_call_hook(my_hook_fn)
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.