DS DevShelfHub Projects · AI tools
Tutorials / CrewAI / Reference / Methods / replay()
Method Crew

replay(): Reference Guide

By DevShelfHub

Re-runs a previous kickoff starting from a specific task — useful for recovery and iteration.

See the CrewAI methods catalog, CrewAI introduction, kickoff() reference, and core concepts for surrounding context.

What is replay()?

Crew.replay(task_id) is the Python API mirror of `crewai replay -t <id>`: it rehydrates the crew from persisted kickoff state, reuses serialized outputs for every task that already finished before the breakpoint, and only executes work from the chosen task onward. That makes it the fastest way to tune a brittle formatter, tighten an `expected_output` contract, or swap a tool on the last hop when everything upstream was expensive or non-deterministic enough that you do not want another full bill.

The `task_id` you pass is the identifier CrewAI associated with that task during the original run (surfaced in logs, traces, and train/test tooling). The optional `inputs` dict lets you patch kickoff-level variables for the replayed segment without pretending earlier tasks re-ran: treat those overrides as surgical, not as a substitute for a fresh kickoff when world state or retrieved documents changed.

Operationally, replay assumes the cached graph is still valid. If you changed agent prompts, tool implementations, embedding models, or external APIs that upstream tasks depended on, prefer a clean `kickoff()` so you are not debugging against stale context. In CI, pin seeds and fixtures when you rely on replay for flaky-task isolation so comparisons stay meaningful week to week.

Use Cases

  • • Debugging late steps
  • • Iterating on the final task only

Key Features

  • ✓ Reuses cached outputs
  • ✓ task-id targeted

When NOT to Use

When upstream data has changed — full kickoff() is safer.

Notes

Stale cache after prompt or tool edits

Replay trusts prior task outputs. If you changed anything that would have altered upstream tokens, run a full kickoff so you are not iterating on a ghost trace.

Determinism and comparisons

When you replay inside train() or offline eval harnesses, keep model versions and tool doubles fixed so quality deltas reflect your change, not provider drift.

Secrets and PII in cached payloads

Cached outputs may still contain redacted-but-sensitive strings. Treat replay artifacts like production logs: restrict disk paths, rotate pickles, and scrub before sharing.

CLI vs Python entry points

Operators often discover task IDs via `crewai replay` help output or prior terminal logs, while services call crew.replay directly. Keep identifiers aligned so runbooks stay copy-pasteable.

Parameters

Parameter Type Required Purpose
task_id str No ID of the task to start replay from.
inputs dict | None No Optional overrides for the replay run.

Code Examples

CLI

python 
crewai replay -t abc-123

Python resume after a failed final task

python 
from crewai import Crew

# task_id comes from logs / train harness after the failed kickoff
result = crew.replay(task_id="task-uuid-from-last-run")
print(result.raw)

Replay with narrowed inputs

python 
crew.replay(
    task_id="write-section",
    inputs={"tone": "more concise", "max_words": 400},
)

When to Use

Debugging a late-stage task without re-running the whole crew.

Common Mistakes

❌ Replaying without recomputing changed upstream tasks

✅ Run kickoff() if upstream data shifted.

Related: @tool decorator reference, Agent class reference, and the first Crew tutorial.

replay() FAQ

What is replay() in CrewAI?

Re-runs a previous kickoff starting from a specific task — useful for recovery and iteration. Crew.replay(task_id) is the Python API mirror of `crewai replay -t <id>`: it rehydrates the crew from persisted kickoff state, reuses serialized outputs for every task that already finished before the breakpoint, and only executes work from the chosen task onward. That makes it the fastest way to tune a brittle formatter, tighten an `expected_output` contract, or swap a tool on the last hop when everything upstream was expensive or non-deterministic enough that you do not wan…

Which CrewAI types expose the method replay()?

DevShelfHub documents replay() on Crew. The reference maps it to Python module crewai.Crew — pin your installed crewai version and match imports to the snippet on this page.

When should I use replay()?

Debugging a late-stage task without re-running the whole crew.

When should I avoid replay()?

When upstream data has changed — full kickoff() is safer.

How do I call replay() from Python?

crew.replay(task_id='abc-123')

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.