Track conversational flow turn usage in telemetry

[lorenzejay]

Note

Low Risk
Observability and experimental conversational API changes only; no auth or data-path changes, with behavior guarded by tests.

Overview
Adds conversation turn lifecycle events (conversation_turn_started, conversation_turn_completed, conversation_turn_failed with session_id) and wires them through the public events surface and EventTypes.

handle_turn now emits ConversationTurnStartedEvent at turn start; on success it emits completed (after awaiting handler completion via _emit_terminal_conversation_turn_event); on failure it emits failed instead of completed, with errors serialized on the failed event. Terminal emissions block up to 30s on handler futures so telemetry/listeners finish before the turn returns.

Telemetry: EventListener records feature_usage_span("flow:conversation_turn") on ConversationTurnCompletedEvent.

CLI: _run_conversational_flow_tui instantiates EventListener() before CrewRunApp so the TUI receives these events.

Tests cover turn pairing, failure path, telemetry, and TUI listener initialization.

^{Reviewed by Cursor Bugbot for commit 9371ec5. Bugbot is set up for automated code reviews on this repo. Configure here.}

Summary by CodeRabbit

• New Features
  • Added conversational flow turn lifecycle events: started, completed, and failed (with session_id).
  • Conversational flow TUI now initializes event listening to handle these turn events.
• Bug Fixes
  • The event system now recognizes and processes the new turn-start/completed/failed events.
  • Telemetry is recorded when a conversational turn completes.
• Tests
  • Expanded coverage for started/completed emission (including session_id), failure-path behavior, telemetry on completed turns, and TUI event listener initialization.

[corridor-security]

Summary: This PR adds a new conversational flow turn-start event and telemetry usage tracking for conversational flows; no exploitable security vulnerabilities were identified.

Risk: Low risk. The changes are limited to internal event emission and telemetry counting, with no new authentication, authorization, data access, external request, or user-facing execution surface.

[coderabbitai]

📝 Walkthrough

Walkthrough

The PR adds conversation turn started, completed, and failed events, exports them through the events API, emits them during conversational turn handling, records telemetry when completed turn events are observed, and initializes the event listener before the conversational TUI runs.

Changes

Conversation turn lifecycle events

Layer / File(s)	Summary
Event contract and exports lib/crewai/src/crewai/events/types/flow_events.py, lib/crewai/src/crewai/events/event_types.py, lib/crewai/src/crewai/events/__init__.py	The new conversation turn lifecycle event classes are defined, added to EventTypes, and exported by crewai.events.
Turn lifecycle emission lib/crewai/src/crewai/experimental/conversational_mixin.py	handle_turn() emits started, failed, and completed events around the conversational turn execution and clears pending turn state in finally.
Telemetry listener and tests lib/crewai/src/crewai/events/event_listener.py, lib/crewai/tests/test_flow_conversation.py	EventListener.setup_listeners subscribes to ConversationTurnCompletedEvent, and the flow tests cover turn event emission, failure handling, and telemetry handling.
TUI event listener initialization lib/cli/src/crewai_cli/kickoff_flow.py, lib/cli/tests/test_kickoff_flow.py	_run_conversational_flow_tui() creates an EventListener before constructing and running CrewRunApp, and the CLI test verifies the call order and returned result.

Suggested reviewers

• greysonlalonde
• vinibrsl
• joaomdmoura

🚥 Pre-merge checks | ✅ 4 | ❌ 1

❌ Failed checks (1 warning)

Check name	Status	Explanation	Resolution
Docstring Coverage	⚠️ Warning	Docstring coverage is 29.63% which is insufficient. The required threshold is 80.00%.	Write docstrings for the functions missing them to satisfy the coverage threshold.

✅ Passed checks (4 passed)

Check name	Status	Explanation
Title check	✅ Passed	The title clearly matches the main change by describing telemetry tracking for conversational flow turns.
Linked Issues check	✅ Passed	Check skipped because no linked issues were found for this pull request.
Out of Scope Changes check	✅ Passed	Check skipped because no linked issues were found for this pull request.
Description Check	✅ Passed	Check skipped - CodeRabbit’s high-level summary is enabled.

_{✏️ Tip: You can configure your own custom pre-merge checks in the settings.}

✨ Finishing Touches

📝 Generate docstrings

• Create stacked PR
• Commit on current branch

🧪 Generate unit tests (beta)

• Create PR with unit tests
• Commit unit tests in branch lorenze/feat/track-conversational-flow-usage

---

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.}

[lucasgomide]

LGTM

I took a quick look here and I'm missing a ConversationTurnCompletedEvent . OTel spans has start/end fields, without an event like taht I would need to guess when the span close. Nothing blocker I would add it later, but would be great to have it from day 0
Also add the following attributes to ConversationTurnCompleted (status: success/error , error: error detail) + the same ConversationTurnStarted

[cursor]

Cursor Bugbot has reviewed your changes and found 1 potential issue.

^{❌ Bugbot Autofix is OFF. To automatically fix reported issues with cloud agents, enable autofix in the Cursor dashboard.}

^{Reviewed by Cursor Bugbot for commit 06db116. Configure here.}

[coderabbitai]

Actionable comments posted: 1

🤖 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/experimental/conversational_mixin.py`:
- Around line 345-350: The terminal event dispatch in the conversational mixin
can still escape if crewai_event_bus.emit(self, event) raises before the guarded
future.result() call. Update the event dispatch flow in the relevant method on
ConversationalMixin so both emit and future.result(timeout=30) are wrapped in
the same try/except, with a None check still short-circuiting safely. Keep the
existing failure handling so kickoff/turn completion and the surrounding finally
logic are not disrupted by dispatch errors.

🪄 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: f2a7aefd-14da-4290-8fcf-b072845e9689

📥 Commits

Reviewing files that changed from the base of the PR and between 06db116 and ebc4e9b.

📒 Files selected for processing (4)

• lib/cli/src/crewai_cli/kickoff_flow.py
• lib/cli/tests/test_kickoff_flow.py
• lib/crewai/src/crewai/experimental/conversational_mixin.py
• lib/crewai/tests/test_flow_conversation.py

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

• lib/crewai/tests/test_flow_conversation.py