fix: support async callables in akickoff before/after callbacks

[ashusnapx]

Summary

Fixes silent discarding of async callables in Crew.akickoff().

Closes #6481

Problem

Crew.akickoff() is a native async execution path, but before_kickoff_callbacks and after_kickoff_callbacks were invoked synchronously with no inspect.isawaitable check. Async callables were silently discarded — their coroutine objects were never awaited.

async def my_callback(result):
    await some_async_operation()  # never awaited
    return result

crew = Crew(..., after_kickoff_callbacks=[my_callback])
await crew.akickoff()  # callback silently discarded

Fix

Component	Change
after_kickoff_callbacks in akickoff()	Added inspect.isawaitable check + await
before_kickoff_callbacks in akickoff()	Created aprepare_kickoff() async variant that awaits async callbacks

Follows the same pattern used by task_callback and step_callback throughout the codebase:

cb_result = callback(result)
if inspect.isawaitable(cb_result):
    await cb_result

Files Changed

File	Change
crew.py	Added import inspect, fixed after_callback loop, imports aprepare_kickoff
crews/utils.py	Added aprepare_kickoff() async variant with inspect.isawaitable for before_callbacks
tests/crew/test_async_crew.py	3 new tests: async before, async after, mixed sync+async

Tests

# Run async crew tests
pytest lib/crewai/tests/crew/test_async_crew.py -v

# Run all crew tests
pytest lib/crewai/tests/test_crew.py lib/crewai/tests/crew/ -v

• 14 async crew tests pass (3 new)
• ruff: all checks passed
• mypy: no issues found

[coderabbitai]

No actionable comments were generated in the recent review. 🎉

ℹ️ Recent review info

⚙️ Run configuration

Configuration used: Organization UI

Review profile: CHILL

Plan: Pro Plus

Run ID: d2a72bd9-a054-4594-94e8-ef3e5bfb7ada

📥 Commits

Reviewing files that changed from the base of the PR and between 3cfba59 and 60a7679.

📒 Files selected for processing (1)

• lib/crewai/src/crewai/crews/utils.py

🚧 Files skipped from review as they are similar to previous changes (1)

• lib/crewai/src/crewai/crews/utils.py

---

📝 Walkthrough

Walkthrough

Adds asynchronous kickoff preparation in crews/utils.py, updates Crew.akickoff to await before and after callback results, and extends async kickoff tests for callback completion and ordering.

Changes

Async before/after kickoff callback support

Layer / File(s)	Summary
Shared and asynchronous kickoff preparation lib/crewai/src/crewai/crews/utils.py	Extracts shared kickoff setup helpers, preserves synchronous preparation, and adds aprepare_kickoff with awaitable before_kickoff_callbacks support.
Native async kickoff integration lib/crewai/src/crewai/crew.py	Uses awaited asynchronous preparation in akickoff and awaits awaitable after_kickoff_callbacks results.
Async callback validation lib/crewai/tests/crew/test_async_crew.py	Adds tests verifying async before/after callbacks are awaited and mixed callback types execute in the expected order.

Sequence Diagram(s)

sequenceDiagram
  participant Caller
  participant Crew as Crew.akickoff
  participant Utils as aprepare_kickoff
  participant BeforeCB as before_kickoff_callbacks
  participant AfterCB as after_kickoff_callbacks

  Caller->>Crew: await akickoff(inputs)
  Crew->>Utils: await aprepare_kickoff(crew, inputs)
  Utils->>BeforeCB: invoke callback chain
  BeforeCB-->>Utils: result or awaitable
  Utils->>Utils: await awaitable result
  Utils-->>Crew: normalized inputs
  Crew->>AfterCB: invoke callback chain
  AfterCB-->>Crew: result or awaitable
  Crew->>Crew: await awaitable result
  Crew-->>Caller: CrewOutput

Loading

Suggested reviewers: vinibrsl

🚥 Pre-merge checks | ✅ 5

✅ Passed checks (5 passed)

Check name	Status	Explanation
Title check	✅ Passed	The title clearly matches the main change: adding async support for kickoff before/after callbacks.
Description check	✅ Passed	The description is directly related to the code changes and the reported async callback bug.
Linked Issues check	✅ Passed	The changes satisfy #6481 by awaiting async after callbacks and adding an async kickoff preparation path for before callbacks.
Out of Scope Changes check	✅ Passed	The refactor into shared kickoff helpers is implementation detail supporting the requested async callback fix, not unrelated scope.
Docstring Coverage	✅ Passed	Docstring coverage is 100.00% which is sufficient. The required threshold is 80.00%.

✨ Finishing Touches

🧪 Generate unit tests (beta)

• Create PR with unit tests

⚔️ Resolve merge conflicts

• Resolve merge conflict in branch feat/async-callback-fix

---

Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out.

❤️ Share

• X
• Mastodon
• Reddit
• LinkedIn

_{Comment @coderabbitai help to get the list of available commands.}

[coderabbitai]

Actionable comments posted: 2

🤖 Prompt for all review comments with AI agents

Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.

Inline comments:
In `@lib/crewai/src/crewai/crews/utils.py`:
- Around line 362-474: The kickoff preparation logic is duplicated between
prepare_kickoff and aprepare_kickoff, creating drift risk as shared behavior
changes over time. Extract the common control flow into a shared internal helper
used by both functions, and keep only the before_kickoff_callbacks execution
different by injecting a callback runner that either returns directly or awaits
awaitable results. Preserve the existing behavior around crewai_event_bus
emission, store_files, _set_tasks_callbacks, setup_agents, and planning in the
shared helper.
- Around line 423-431: The kickoff planning path is still blocking the event
loop because `aprepare_kickoff` ultimately calls `crew._handle_crew_planning()`
synchronously via `CrewPlanner._handle_crew_planning()` and `execute_sync()`.
Update the async kickoff flow in `utils.py` so planning is offloaded to a thread
or handled through a non-blocking async path before returning from `akickoff()`,
using the existing `aprepare_kickoff`, `crew._handle_crew_planning`, and
`CrewPlanner` hooks to locate the change.

🪄 Autofix (Beta)

Fix all unresolved CodeRabbit comments on this PR:

• Push a commit to this branch (recommended)
• Create a new PR with the fixes

---

ℹ️ Review info

⚙️ Run configuration

Configuration used: Organization UI

Review profile: CHILL

Plan: Pro Plus

Run ID: 460ccfbf-0675-415f-a37f-8ca756db70d3

📥 Commits

Reviewing files that changed from the base of the PR and between 289686a and eb92e41.

📒 Files selected for processing (3)

• lib/crewai/src/crewai/crew.py
• lib/crewai/src/crewai/crews/utils.py
• lib/crewai/tests/crew/test_async_crew.py

[ErenAta16]

Same underlying fix as #6500 and #6482 (also open) — the crew.py change here is identical to both. Where this one differs is crews/utils.py: it copy-pastes the full body of prepare_kickoff into a new aprepare_kickoff rather than factoring out the shared setup/teardown logic, which #6500 and #6482 both do via extracted helpers. Functionally correct either way and the test coverage here (including the test_akickoff_mixed_sync_async_callbacks ordering check) is solid, but the duplication means a future change to the shared kickoff-preparation logic would need to be applied in two places instead of one — worth weighing against the other two when picking which of the three to merge.

[ashusnapx]

Refactored - extracted shared logic into _prepare_kickoff_common and _run_before_callbacks. Both prepare_kickoff and aprepare_kickoff now call the shared helpers. No more duplication.

[ErenAta16]

Confirmed - prepare_kickoff and aprepare_kickoff now both go through _normalize_inputs and _prepare_kickoff_common, with _run_before_callbacks handling the sync path and the async version inlining its own inspect.isawaitable loop (needed since it has to await mid-loop, so it can't reuse the sync helper as-is). Ran the full test_async_crew.py - 14 passed, including the mixed sync/async callback case. No more full-body duplication between the two entry points. Good refactor.

[ashusnapx]

Thanks for confirming. Ready for maintainer review.

[ErenAta16]

@ashusnapx I think there's been a mix-up, and I'd rather flag it than let it ride: the sentinel problem I described was in #6500, not here. Your original version didn't have it. In my comparison table on #6482 I had #6494 marked "callbacks can double-run: no", which I re-verified before writing:

=== single callback returning None ===
   sync invocations:  1
   async invocations: 1     <- original #6494, no double-run

The double-run needs the "has the caller already applied the callbacks?" flag that #6500 uses. Your structure never had that question to answer, since aprepare_kickoff always runs its own loop.

Unfortunately 60a7679 has introduced a real divergence while fixing the non-problem. The if normalized is None: normalized = {} guard inside the sync loop isn't a first-iteration initializer, it re-normalizes on every pass. That's what recovers when a callback returns None: the next callback still receives a dict. Replacing it with an _UNSET check that only fires on the first iteration drops that recovery.

Two callbacks, first one mutates in place and returns None:

-- sync (current main) --
   cb2 received: {'from_cb2': True}   -> completes

-- async (60a7679) --
   TypeError: 'NoneType' object does not support item assignment

So akickoff now crashes on a callback chain that kickoff handles. That's a worse failure than the one this PR set out to fix, because it's an exception rather than a silent no-op, and it only triggers with two or more callbacks where an early one doesn't return the dict.

Keeping the per-iteration guard alongside the awaiting is enough, no sentinel needed:

async def aprepare_kickoff(crew, inputs, input_files=None):
    normalized = _normalize_inputs(crew, inputs)
    for before_callback in crew.before_kickoff_callbacks:
        if normalized is None:
            normalized = {}
        result = before_callback(normalized)
        if inspect.isawaitable(result):
            result = await result
        normalized = result
    return _prepare_kickoff_common(crew, normalized, input_files)

That's line-for-line the sync loop with two lines added for awaiting, which also makes it obvious at review time that the two paths agree.

On your docstring's reasoning, "the next callback would then receive the pre-callback inputs instead of the callback's return value": that isn't what the sync code does. It passes a fresh {}, not the pre-callback inputs, because normalized was already overwritten with None by the assignment before the guard re-runs. So there's nothing to preserve there.

Also worth a test either way. None of the three PRs covers a multi-callback chain where an early callback returns None, which is why this slipped through, and it's the case that separates the two designs.

Sorry for the confusion on my end, my #6482 comment named #6500 but I can see how it read as applying to all three.