DS DevShelfHub Projects · AI tools
Tutorials / CrewAI / Reference / Classes / LLMCallHookContext
Class hooks

LLMCallHookContext: Reference Guide

By DevShelfHub

Context passed to before/after LLM-call hooks — carries prompt, response, model, agent identity.

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

What is LLMCallHookContext?

LLMCallHookContext is the mutable envelope CrewAI passes into @before_llm_call_crew and @after_llm_call_crew handlers (and the imperative register_before_llm_call_hook APIs). Fields typically include the serialized prompt, partial or final model output, resolved model name, token usage metadata, and identifiers tying the call back to an agent or task so your hook can log, redact, or short-circuit consistently.

Before hooks run while the planner still has time to change course: use them to strip secrets, inject dynamic system reminders, or enforce spend caps by raising a controlled error. After hooks observe the completed exchange — ideal for metrics export, PII scrubbing on responses, or attaching trace spans without mutating business logic inside agents.

Because hooks execute on the hot path next to every LLM invocation, keep work O(milliseconds) unless you offload to a queue. Assume re-entrancy when nested tools trigger auxiliary model calls, and never rely on global mutable state without locks.

When to Use

Inside @before_llm_call_crew / @after_llm_call_crew bodies.

Use Cases

  • • Prompt augmentation
  • • Response sanitization
  • • Cost gating

Key Features

  • ✓ prompt / response
  • ✓ agent / task metadata
  • ✓ model identity

When NOT to Use

Outside hook code.

Notes

Mutate intentionally

Changing ctx.prompt alters what the model sees — great for redaction, dangerous for silent behavior changes. Document hooks as part of your public contract.

Avoid network I/O inline

Push telemetry batches to a background worker. Synchronous HTTP inside hooks adds tail latency to every agent step.

Mind ordering with other hooks

Multiple hooks compose; conflicting mutations (double prefixing prompts) are easy to introduce. Keep hooks idempotent or namespaced.

Tests

Unit-test hooks by constructing minimal ctx objects or exercising register_* APIs with stub crews so regressions show up without full kickoffs.

Import

python 
from crewai.hooks import LLMCallHookContext

Code Examples

Redact emails before the model call

python 
import re
from crewai.hooks import LLMCallHookContext

EMAIL = re.compile(r'[A-Z0-9._%+-]+@[A-Z0-9.-]+\.[A-Z]{2,}', re.I)

def scrub(ctx: LLMCallHookContext):
    ctx.prompt = EMAIL.sub('[redacted-email]', ctx.prompt)

Structured log after completion

python 
from crewai.hooks import LLMCallHookContext

def audit(ctx: LLMCallHookContext):
    print({'model': ctx.model, 'agent': getattr(ctx, 'agent_role', None), 'prompt_tokens': getattr(ctx.usage, 'prompt', None)})

Decorator wiring

python 
from crewai.hooks import before_llm_call_crew, LLMCallHookContext

@before_llm_call_crew
def stamp(ctx: LLMCallHookContext):
    ctx.prompt = '[AUDITED] ' + ctx.prompt

Common Mistakes

❌ Throwing bare exceptions without context

✅ Wrap failures with crew-visible errors so planners can retry or abort cleanly.

LLMCallHookContext FAQ

What is LLMCallHookContext in CrewAI?

Context passed to before/after LLM-call hooks — carries prompt, response, model, agent identity. LLMCallHookContext is the mutable envelope CrewAI passes into @before_llm_call_crew and @after_llm_call_crew handlers (and the imperative register_before_llm_call_hook APIs). Fields typically include the serialized prompt, partial or final model output, resolved model name, token usage metadata, and identifiers tying the call back to an agent or task so your hook can log, redact, or short-circuit consistently. Before hooks run while the planner still has time to change cours…

Which package defines the CrewAI class LLMCallHookContext?

DevShelfHub maps LLMCallHookContext to Python module crewai.hooks (package path crewai.hooks in this reference). Pin your installed crewai version and match imports to the snippet on this page.

When should I use LLMCallHookContext?

Inside @before_llm_call_crew / @after_llm_call_crew bodies.

When should I avoid using LLMCallHookContext?

Outside hook code.

How do I import LLMCallHookContext in Python?

from crewai.hooks import LLMCallHookContext

Where can I explore more CrewAI API reference pages?

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