Step Hooks

Step hooks intercept each unit of work inside an execution: every crew task and every flow method. Use them to inspect or rewrite what goes into a step, transform what comes out, or trace step-by-step progress — without touching the level of individual LLM or tool calls.

Overview

Two interception points cover steps:

Point	When	`ctx.payload`
`PRE_STEP`	Before a task or flow method runs	step input (see below)
`POST_STEP`	After a task or flow method runs	step output (see below)

What the payload holds depends on ctx.kind:

`ctx.kind`	`PRE_STEP` payload	`POST_STEP` payload
`"task"`	The context string passed to the agent	The `TaskOutput` object
`"flow_method"`	The method’s parameters as a `dict`	The method’s return value

For flow methods, positional arguments appear in the params dict under _0, _1, … keys and keyword arguments under their own names; edits and replacements are mapped back onto the actual call.

Hook Signature

from crewai.hooks import on, HookAborted, InterceptionPoint

@on(InterceptionPoint.PRE_STEP)
def step_hook(ctx) -> Any | None:
    # Mutate ctx.payload in place, or
    # return a non-None value to replace it, or
    # raise HookAborted(reason, source) to stop the step
    return None

Context Schema

Both points receive a StepContext:

class StepContext(InterceptionContext):
    payload: Any            # Step input (pre) or step output (post)
    kind: str | None        # "task" or "flow_method"
    step_name: str | None   # Task name/description, or flow method name
    output: Any             # POST_STEP only: same object as payload
    agent: Any              # Task steps: the executing agent (else None)
    agent_role: str | None  # Task steps: the agent's role (else None)
    task: Any               # Task steps: the Task instance (else None)
    crew: Any               # None for step points
    flow: Any               # Flow-method steps: the Flow instance (else None)

For task steps, step_name is the task’s name (falling back to its description). For flow-method steps, it is the method name.

Common Use Cases

Step Tracing

@on(InterceptionPoint.POST_STEP)
def trace_steps(ctx):
    print(f"{ctx.kind} '{ctx.step_name}' finished")

Rewriting Task Context

@on(InterceptionPoint.PRE_STEP)
def inject_disclaimer(ctx):
    if ctx.kind != "task":
        return None
    return f"{ctx.payload}\n\nNote: treat all figures as estimates."

Transforming Task Output

@on(InterceptionPoint.POST_STEP)
def normalize_output(ctx):
    if ctx.kind != "task":
        return None
    ctx.payload.raw = ctx.payload.raw.strip()

POST_STEP runs before the task’s output is stored, so rewrites propagate everywhere the output is used: downstream task context, callbacks, the final crew output, and the task’s output_file on disk.

Guarding Flow Methods

@on(InterceptionPoint.PRE_STEP)
def guard_publish(ctx):
    if ctx.kind == "flow_method" and ctx.step_name == "publish":
        if not ctx.flow.state.get("reviewed"):
            raise HookAborted(reason="publish requires review", source="review-gate")

Filtering by Agent

Step hooks support the same agents= filter as the other points (matched against the executing agent’s role on task steps):

@on(InterceptionPoint.POST_STEP, agents=["Researcher"])
def log_research_steps(ctx):
    print(f"research step done: {ctx.step_name}")

Aborting a Step

Raising HookAborted in PRE_STEP stops the step before any agent or method work happens, and the abort propagates out of the execution with its reason — it is not swallowed. Any other exception raised by a step hook is swallowed (fail-open), like at every other point.

Managing Hooks in Tests

from crewai.hooks import clear_all_hooks

clear_all_hooks()  # Clears every point, including steps

Get Started

Guides

Core Concepts

MCP Integration

Tools

Observability

Learn

Telemetry

Overview

Hook Signature

Context Schema

Common Use Cases

Step Tracing

Rewriting Task Context

Transforming Task Output

Guarding Flow Methods

Filtering by Agent

Aborting a Step

Managing Hooks in Tests

​Overview

​Hook Signature

​Context Schema

​Common Use Cases

​Step Tracing

​Rewriting Task Context

​Transforming Task Output

​Guarding Flow Methods

​Filtering by Agent

​Aborting a Step

​Managing Hooks in Tests

​Related Documentation

Overview

Hook Signature

Context Schema

Common Use Cases

Step Tracing

Rewriting Task Context

Transforming Task Output

Guarding Flow Methods

Filtering by Agent

Aborting a Step

Managing Hooks in Tests

Related Documentation