CrewAI in production
CrewAI's own production tooling — limits and guardrails, event listeners, OpenTelemetry, tracing, hooks, token accounting, checkpoints, offline tests with a stub LLM, and deploying with crewai deploy or your own container.
Verified against
crewai1.15.41 (checked 2026-11-19; source:crewai/events/,crewai/hooks/,crewai/execution.py,crewai/state/,crewai_cli/deploy/). The Python examples were run against that release with a stub LLM; the pytest files pass offline.
This page covers what CrewAI itself gives you for running crews and flows in production. Generic service plumbing (web frameworks, Kubernetes, queues) is not CrewAI-specific and is only touched on where CrewAI changes the advice.
Checklist
Section titled “Checklist”| Concern | CrewAI feature | Section |
|---|---|---|
| Runaway loops and cost | max_iter, max_rpm, max_execution_time, tool max_usage_count | Limits |
| Bad output | Task guardrail / guardrails, output_pydantic / response_model | Limits |
| Tools that fail quietly | tool_failure_policy | Limits |
| Logs and metrics | Event listeners on crewai_event_bus | Event listeners |
| Traces | Your own OpenTelemetry spans from listeners; CrewAI AMP tracing | Tracing |
| Policy enforcement | before_tool_call / after_llm_call hooks | Hooks |
| Cost reporting | CrewOutput.token_usage, LLMCallCompletedEvent.usage | Tokens |
| Crashes mid-run | Crew(checkpoint=...), @persist for flows | Checkpoints |
| Regressions | pytest with a stub BaseLLM; crewai test, crewai eval | Testing |
| Shipping | crewai deploy validate/create/push, or your own container | Deploying |
Configuration and secrets
Section titled “Configuration and secrets”- Keep provider keys (
OPENAI_API_KEY,ANTHROPIC_API_KEY, …) in the environment. CrewAI and the provider SDKs read them from there;LLM(api_key=...)is only needed for non-standard setups. - The project scaffold puts a
.envin the project root and lists it in.gitignore. It is for local runs. NeverCOPYit into an image or commit it; inject secrets at runtime (docker run --env-file, Kubernetes Secrets, your platform’s secret store). crewai deploy createreads your local.envand sends its variables to CrewAI AMP as deployment environment variables, after showing you the list to confirm. Check that file before you deploy, or keep production values out of it and set them on the platform.- Pin the model per agent (
llm=LLM(model="openai/gpt-6-luna")) rather than relying on the default. An agent withoutllmreads theMODEL,MODEL_NAMEorOPENAI_MODEL_NAMEenvironment variable, then falls back to CrewAI’s built-in default (gpt-6-lunain 1.15.41), which can change between releases. Provider SDKs other than OpenAI are extras:pip install "crewai[anthropic]",crewai[google-genai],crewai[bedrock],crewai[litellm]. - CrewAI sends anonymous usage telemetry by default. Turn it off with
CREWAI_DISABLE_TELEMETRY=true(orCREWAI_DISABLE_TRACKING=true).OTEL_SDK_DISABLED=truealso works but disables every OpenTelemetry SDK in the process, including your own tracing. LeaveCrew(share_crew=False)(the default) unless you intend to share crew data with CrewAI.
Limits, guardrails and failure policy
Section titled “Limits, guardrails and failure policy”from crewai import Agent, Crew, Task, LLMfrom crewai.tasks.task_output import TaskOutput
llm = LLM(model="openai/gpt-6-luna", timeout=60)
def under_300_words(output: TaskOutput) -> tuple[bool, str]: words = len(output.raw.split()) if words > 300: return False, f"{words} words; cut it to 300 or fewer." return True, output.raw
writer = Agent( role="Writer", goal="Write accurate product summaries", backstory="Technical writer for a hardware company.", llm=llm, max_iter=10, # reasoning iterations per task (default 25) max_execution_time=120, # wall-clock seconds per task max_retry_limit=2, # retries after a task-level error tool_failure_policy="raise", # a tool that reports failure aborts the task)
summary = Task( description="Summarise {product} for the catalogue.", expected_output="A plain-text summary under 300 words.", agent=writer, guardrail=under_300_words, guardrail_max_retries=2,)
crew = Crew(agents=[writer], tasks=[summary], max_rpm=30) # requests per minute, whole crewprint(crew.kickoff(inputs={"product": "a USB-C dock"}).raw)- Guardrails run after the task; a failure sends the reason back to the agent for another attempt, and
guardrail_max_retries=2allows three attempts in all before the task raises. On success, return the output (output.raw) as the second value; that value becomes the task output.Agent(guardrail=...)is not a substitute: it only applies toAgent.kickoff(), not to tasks in a crew. See Task API → Guardrails. tool_failure_policy("ignore","warn","raise") decides what happens when a tool call fails: the tool returned aToolFailure, raised, exceeded its usage cap and so on. Set it on the tool, task, agent or crew (most specific wins); the default is"warn". A tool that merely returns an error string is not treated as failed. See Tools → Reporting tool failures.- Tool caps:
@tool("search", max_usage_count=5)stops a tool after five calls. The count lives on the tool object, so it accumulates across tasks until you callreset_usage_count(). LLM(timeout=...)bounds each model call;max_execution_timebounds the whole task.
Event listeners
Section titled “Event listeners”Every crew, task, agent, LLM call, tool call, flow method, memory and knowledge operation emits a typed event on crewai_event_bus. A listener subclass registers its handlers once and then sees every run in the process:
import jsonimport logging
from crewai.events import ( BaseEventListener, CrewKickoffCompletedEvent, CrewKickoffFailedEvent, LLMCallFailedEvent, TaskFailedEvent, ToolFailureDetectedEvent,)
log = logging.getLogger("crew.ops")
def emit(kind: str, **fields) -> None: log.info(json.dumps({"event": kind, **fields}, default=str))
class OpsListener(BaseEventListener): def setup_listeners(self, crewai_event_bus): @crewai_event_bus.on(CrewKickoffCompletedEvent) def on_crew_done(source, event): emit("crew_completed", crew=event.crew_name, total_tokens=event.total_tokens)
@crewai_event_bus.on(CrewKickoffFailedEvent) def on_crew_failed(source, event): emit("crew_failed", crew=event.crew_name, error=event.error)
@crewai_event_bus.on(TaskFailedEvent) def on_task_failed(source, event): agent = event.task.agent.role if event.task and event.task.agent else None emit("task_failed", task=event.task_name, agent=agent, error=event.error)
@crewai_event_bus.on(ToolFailureDetectedEvent) def on_tool_failure(source, event): emit("tool_failure", tool=event.tool_name, agent=event.agent_role, code=event.failure.code, error=event.failure.message, policy=event.policy.value)
@crewai_event_bus.on(LLMCallFailedEvent) def on_llm_failed(source, event): emit("llm_failed", model=event.model, error=event.error)
ops_listener = OpsListener() # instantiate once, at import time, before any kickoff- Task events do not fill in
agent_role(it isNoneonTaskStartedEvent,TaskCompletedEventandTaskFailedEventin 1.15.41), which is why the task handler above reads the agent fromevent.task. Tool events do carry it. - A tool that raises, or returns a
ToolFailure, produces aToolFailureDetectedEvent(unless the policy is"ignore"); in our runs it was this event, notToolUsageErrorEvent, that fired for a tool exception on the function-calling path. - Handlers take
(source, event). Sync handlers run on a thread pool, so they don’t block the agents; callcrewai_event_bus.flush()when you need them finished (in tests, or before a short-lived process exits). - Event families include
Crew*,Task*,Agent*,LLMCall*,LLMStreamChunkEvent,ToolUsage*,ToolFailureDetectedEvent,MCP*,Memory*,Knowledge*,Flow*,MethodExecution*,HumanFeedback*,Conversation*andCheckpoint*; all are importable fromcrewai.events. crewai_event_bus.scoped_handlers()is a context manager that removes handlers registered inside it, which keeps tests independent.- Use
Crew(step_callback=..., task_callback=...)only for quick per-crew hooks; listeners are the general mechanism.
Tracing
Section titled “Tracing”Your own OpenTelemetry backend
Section titled “Your own OpenTelemetry backend”CrewAI does not install a global OpenTelemetry TracerProvider, so spans for your backend come from a listener. This one records a span per task:
from opentelemetry import tracefrom opentelemetry.sdk.trace import TracerProviderfrom opentelemetry.sdk.trace.export import BatchSpanProcessor, ConsoleSpanExporter
from crewai.events import ( BaseEventListener, TaskCompletedEvent, TaskFailedEvent, TaskStartedEvent,)
provider = TracerProvider()provider.add_span_processor(BatchSpanProcessor(ConsoleSpanExporter())) # swap for an OTLP exportertrace.set_tracer_provider(provider)tracer = trace.get_tracer("my-crew")
class TaskSpans(BaseEventListener): def __init__(self): self._spans = {} super().__init__()
def setup_listeners(self, crewai_event_bus): @crewai_event_bus.on(TaskStartedEvent) def started(source, event): self._spans[event.task_id] = tracer.start_span(f"task {event.task_name or event.task_id}")
@crewai_event_bus.on(TaskCompletedEvent) def completed(source, event): if span := self._spans.pop(event.task_id, None): span.set_attribute("crewai.output_chars", len(event.output.raw)) span.end()
@crewai_event_bus.on(TaskFailedEvent) def failed(source, event): if span := self._spans.pop(event.task_id, None): span.set_status(trace.Status(trace.StatusCode.ERROR, event.error)) span.end()
task_spans = TaskSpans()The same pattern extends to LLMCallStartedEvent / LLMCallCompletedEvent (keyed by event.call_id) and the tool events. Do not set OTEL_SDK_DISABLED=true to silence CrewAI’s telemetry when you use this; it turns these spans into no-ops too.
CrewAI AMP tracing
Section titled “CrewAI AMP tracing”CrewAI can also send execution traces to CrewAI AMP, where crewai eval grades them. Enable it with any one of:
Crew(tracing=True)orFlow(tracing=True)in code;CREWAI_TRACING_ENABLED=truein the environment;crewai traces enable(records your consent in CrewAI’s per-user data;crewai traces statusandcrewai traces disablealso exist).
tracing=False or CREWAI_TRACING_ENABLED=false turns it off for a run. Traces contain prompts and outputs, so treat this as sending data to a third party.
Hooks: block or rewrite calls
Section titled “Hooks: block or rewrite calls”Hooks run synchronously inside the agent loop, so unlike listeners they can change what happens. They are registered globally when the decorated function is defined:
import re
from crewai.hooks import ( LLMCallHookContext, ToolCallHookContext, after_llm_call, before_tool_call,)
EMAIL = re.compile(r"[\w.+-]+@[\w-]+\.[\w.]+")
@before_tool_call(tools=["delete_customer"])def block_deletes(context: ToolCallHookContext) -> bool | None: """Refuse destructive calls unless the agent passed confirmed=True.""" if not context.tool_input.get("confirmed"): return False # the tool does not run; the agent sees "Tool execution blocked by hook" return None
@after_llm_calldef redact_emails(context: LLMCallHookContext) -> str | None: """Mask email addresses in every model response before CrewAI uses it.""" if context.response and EMAIL.search(context.response): return EMAIL.sub("[email]", context.response) return None # keep the response unchangedbefore_llm_callandbefore_tool_callhooks returnFalseto block the call; they may editcontext.messages/context.tool_inputin place (never replace the list or dict).after_llm_callandafter_tool_callhooks return a replacement string, orNoneto keep the original.tools=[...]andagents=[...]filter which calls a hook sees.crewai.hooks.clear_all_global_hooks()removes them all (useful between tests).
Run-level hooks: @on(InterceptionPoint...)
Section titled “Run-level hooks: @on(InterceptionPoint...)”The four decorators above are adapters over a more general mechanism in crewai.hooks. @on(point) registers a function for any interception point, and a hook can stop the operation by raising HookAborted(reason):
| Point | Fires | Context highlights |
|---|---|---|
INPUT / EXECUTION_START | Before a crew (or flow) runs | payload is the inputs dict |
OUTPUT | After the final result is built | payload is the CrewOutput |
EXECUTION_END | After success or failure | status is "completed" or "failed"; error on failure |
PRE_STEP / POST_STEP | Around each task (or flow method) | kind, step_name, payload |
PRE_MODEL_CALL / POST_MODEL_CALL, PRE_TOOL_CALL / POST_TOOL_CALL | Around model and tool calls | The same contexts as the four decorators |
import re
from crewai.hooks import HookAborted, InterceptionPoint, on
@on(InterceptionPoint.INPUT)def reject_banned_topics(ctx): if "forbidden" in str(ctx.payload.get("topic", "")): raise HookAborted("topic not allowed") # kickoff() raises HookAborted
@on(InterceptionPoint.OUTPUT)def redact_ssn(ctx): ctx.payload.raw = re.sub(r"\d{3}-\d{2}-\d{4}", "[ssn]", ctx.payload.raw) # mutate in place
@on(InterceptionPoint.EXECUTION_END)def audit(ctx): print("run finished:", ctx.status)We ran these around a one-task crew: the redaction was visible in both result.raw and result.tasks_output[0].raw, a banned topic made kickoff() raise HookAborted: topic not allowed, and EXECUTION_END reported "failed" for that run. A hook may mutate its context in place, or return a replacement for ctx.payload. Any exception other than HookAborted raised inside a hook is swallowed, so a buggy hook cannot crash a run; it also cannot be relied on to block one. Use clear_all_hooks() between tests.
Token usage
Section titled “Token usage”kickoff() returns a CrewOutput whose token_usage is a UsageMetrics with total_tokens, prompt_tokens, cached_prompt_tokens, completion_tokens, reasoning_tokens, cache_creation_tokens and successful_requests:
result = crew.kickoff(inputs={"product": "a USB-C dock"})usage = result.token_usageprint(usage.prompt_tokens, usage.completion_tokens, usage.cached_prompt_tokens)Multiply by your provider’s current prices to report cost; keep the prices in configuration rather than code, because they change. For per-call figures (per model, per agent), read event.usage and event.model in an LLMCallCompletedEvent listener.
Recovery with checkpoints
Section titled “Recovery with checkpoints”A checkpoint is a JSON snapshot of the run written when chosen events fire. If the process dies, resume from the last one instead of starting again:
from crewai import Agent, Crew, Task, LLM, CheckpointConfig
llm = LLM(model="openai/gpt-6-luna")writer = Agent(role="Writer", goal="Write about {topic}", backstory="Technical writer.", llm=llm)outline = Task(description="Outline an article on {topic}.", expected_output="Five headings.", agent=writer)draft = Task(description="Write the article from the outline.", expected_output="About 800 words.", agent=writer)
crew = Crew( agents=[writer], tasks=[outline, draft], checkpoint=CheckpointConfig(location="./.checkpoints", on_events=["task_completed"], max_checkpoints=20),)crew.kickoff(inputs={"topic": "vector search"})
# After a crash: rebuild the same crew and resume from a saved file# crew.kickoff(from_checkpoint=CheckpointConfig(restore_from="./.checkpoints/main/<file>.json"))crewai checkpoint list ./.checkpointsshows each file with the number of tasks completed;crewai checkpoint resumepicks the latest. See CLI → Checkpoints.- In containers, put
locationon a persistent volume, or use the SQLite provider (crewai.state.provider.sqlite_provider). - Flows can use the same
checkpoint=/from_checkpoint=, or@persistfor state-level resume and paused human review (Flows → Persistence). - Checkpoints contain task outputs and inputs. Treat the directory as sensitive data.
Testing without a model
Section titled “Testing without a model”Unit tests should not call a provider. Subclass BaseLLM with canned replies and pass it as the agent’s llm; everything else (interpolation, task wiring, guardrails, events, flow routing) runs for real. These two files pass with pytest and no API key:
# tests/test_crew.py: runs offline, no API key, no networkfrom typing import Any
from crewai import Agent, Crew, Taskfrom crewai.crews.crew_output import CrewOutputfrom crewai.events import TaskCompletedEvent, crewai_event_busfrom crewai.llms.base_llm import BaseLLM
class ScriptedLLM(BaseLLM): """Returns canned replies in order and records every prompt it was sent."""
replies: list[str] = [] prompts: list[Any] = []
def call(self, messages, tools=None, callbacks=None, available_functions=None, from_task=None, from_agent=None, response_model=None, **kwargs): self.prompts.append(messages) reply = self.replies.pop(0) if self.replies else "done" return f"Thought: I now know the final answer\nFinal Answer: {reply}"
def supports_function_calling(self) -> bool: return False
def build_crew(llm: BaseLLM) -> Crew: analyst = Agent( role="Analyst", goal="Summarise {topic}", backstory="Writes short, factual summaries.", llm=llm, ) summary = Task( description="Summarise {topic} in one sentence.", expected_output="One sentence.", agent=analyst, ) return Crew(agents=[analyst], tasks=[summary])
def test_crew_returns_summary_and_interpolates_inputs(): llm = ScriptedLLM(model="scripted", replies=["Tides are caused by the Moon."]) result = build_crew(llm).kickoff(inputs={"topic": "tides"})
assert isinstance(result, CrewOutput) assert result.raw == "Tides are caused by the Moon." assert "tides" in str(llm.prompts[0]) # {topic} reached the prompt
def test_task_completed_event_fires(): seen = [] with crewai_event_bus.scoped_handlers(): # handlers removed on exit @crewai_event_bus.on(TaskCompletedEvent) def record(source, event): seen.append(event.output.raw)
build_crew(ScriptedLLM(model="scripted", replies=["ok"])).kickoff(inputs={"topic": "x"}) crewai_event_bus.flush() # handlers run on a thread pool
assert seen == ["ok"]# tests/test_flow.py: flow routing is plain Python, so test it without any LLMfrom typing import Literal
from pydantic import BaseModelfrom crewai.flow import Flow, listen, router, start
class TicketState(BaseModel): text: str = ""
class TriageFlow(Flow[TicketState]): @start() def receive(self): return self.state.text
@router(receive) def route(self) -> Literal["urgent", "routine"]: return "urgent" if "outage" in self.state.text.lower() else "routine"
@listen("urgent") def page(self): return "paged"
@listen("routine") def queue(self): return "queued"
def test_outage_pages_on_call(): assert TriageFlow().kickoff(inputs={"text": "EU outage"}) == "paged"
def test_everything_else_is_queued(): assert TriageFlow().kickoff(inputs={"text": "typo"}) == "queued"
def test_router_declares_its_labels(): route = TriageFlow.flow_definition().to_dict()["methods"]["route"] assert route["emit"] == ["urgent", "routine"]- The stub answers in CrewAI’s text format (
Final Answer: ...) and reports no native function calling, which keeps the agent on the text path. To exercise a tool, returnAction: <tool name>/Action Input: {...}first and the final answer on the next call. - For structured output, return JSON matching the model when
response_modelis passed tocall. - Set
CREWAI_DISABLE_TELEMETRY=trueandCREWAI_TRACING_ENABLED=falsein the test environment so nothing leaves the machine.
Evaluation with a real model
Section titled “Evaluation with a real model”crewai test -n 3 -m gpt-6-lunaruns the crew three times and scores each task with an OpenAI model. It costs tokens, and in 1.15.41 it exits 0 even when the run errors, so it is a report rather than a CI gate.crewai evalgrades the last traced run through CrewAI AMP and exits non-zero on a failed gate;crewai eval --models a,bcompares models on a deployment. It needs tracing andcrewai login.
Deploying
Section titled “Deploying”CrewAI AMP
Section titled “CrewAI AMP”CrewAI AMP is CrewAI’s hosted platform. The CLI is the interface; there is no crewai.amp Python API.
crewai login # authenticate the CLIcrewai deploy validate # local pre-flight checks, no networkcrewai deploy create # first deployment (from the git origin remote, or a ZIP upload)crewai deploy push # redeploy after changescrewai deploy status -u <uuid>crewai deploy logs -u <uuid>crewai deploy validate runs the checks create and push run first, and exits non-zero on blocking errors: pyproject.toml with a project name, a lockfile (uv.lock or poetry.lock) that is present and not stale, the src/<package>/ layout and standard crew files (or a Flow subclass in main.py), a resolvable wheel target, a clean import of the crew or flow module, environment variables referenced in code but missing from .env, and the installed crewai against the lockfile pin. It is cheap to run in CI.
Remember that create uploads the variables in your local .env (see Configuration).
Your own container
Section titled “Your own container”A crew is an ordinary Python program, so any container platform works. The CrewAI-specific points:
FROM python:3.12-slimRUN pip install --no-cache-dir uvWORKDIR /appCOPY pyproject.toml uv.lock ./RUN uv sync --frozen --no-install-projectCOPY src ./srcRUN uv sync --frozenENV CREWAI_DISABLE_TELEMETRY=true# No .env in the image: pass secrets at run time, e.g. docker run --env-file prod.env ...CMD ["uv", "run", "run_crew"]run_crewis the console script the classic scaffold defines inpyproject.toml; flow projects define their own.- Memory (LanceDB, under
memory/), knowledge (ChromaDB), flow persistence (flow_states.db) and the latest-kickoff task outputs used bycrewai replay(latest_kickoff_task_outputs.db) are written to CrewAI’s per-user data directory, whose name comes from the project folder. SettingCREWAI_STORAGE_DIRmoves them (we confirmed this for memory, flow persistence and the task-output store). Checkpoints are written to./.checkpointsunlessCheckpointConfig(location=...)says otherwise, andSQLiteFlowPersistence(path)takes an explicit file. Point all of these at a mounted volume or they vanish with the container. Writes to these stores take a lock: a file lock in the system temp directory by default, or a Redis lock whenREDIS_URLis set andredisis installed (crewai_core.lock_store.set_lock_backendswaps in your own). A temp-directory lock only coordinates processes on one machine, so containers that share a network volume should useREDIS_URLor a store built for concurrent writers. - Behind a web API, run kickoffs as background jobs (a run takes seconds to minutes) and build a fresh crew per request instead of sharing one instance between concurrent requests. In async servers use
await crew.akickoff(...)orawait flow.kickoff_async(...);kickoff()blocks the calling thread. - Stream partial output with
Crew(stream=True)/Flow(stream=True), or listen forLLMStreamChunkEvent.