Lorenze/imp/conversational flow traces

[lorenzejay]

Note

Low Risk
Changes are limited to event emission, trace listener registration, and kickoff ordering for conversational/deferred tracing; no auth or data-path changes, with new tests covering the behavior.

Overview
Adds first-class observability for conversational flows: ConversationMessageAddedEvent and ConversationRouteSelectedEvent are defined, exported, wired into the global event union, and recorded by the trace listener. The conversational mixin emits these when users/assistants append messages and when route_conversation picks a route (including previous_intent).

Kickoff ordering in runtime.py is adjusted so deferred multi-turn sessions emit one flow_started per session (later turns restore the stashed event scope instead of re-opening), and pending user messages are applied after flow scope init so transcript events parent correctly under the conversation trace.

Tests cover event payloads, single flow_started under defer_trace_finalization, and message_index=None when routing with an empty transcript.

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

Summary by CodeRabbit

• New Features
  • Conversation message-added and route-selected events added and surfaced through tracing for improved observability of messages and routing decisions.
• Behavior
  • Flow start handling refined to support deferred trace finalization so session tracing can be postponed while preserving correct start semantics and event scope restoration.
• Tests
  • Added tests verifying conversation event emission, routing events, message indexing, and deferred trace finalization across turns.

[coderabbitai]

📝 Walkthrough

Walkthrough

Adds two conversation FlowEvent types, emits them during routing and message appends, wires handlers into tracing, and refactors Flow kickoff to support deferred session-level FlowStartedEvent across multi-turn conversations.

Changes

Conversational flow event observability

Layer / File(s)	Summary
Event type definitions and public exports lib/crewai/src/crewai/events/types/flow_events.py, lib/crewai/src/crewai/events/__init__.py, lib/crewai/src/crewai/events/event_types.py	Defines ConversationMessageAddedEvent and ConversationRouteSelectedEvent as FlowEvent subclasses with typed payloads; adds them to the events package lazy mapping, __all__, and EventTypes.
Trace listener event handlers lib/crewai/src/crewai/events/listeners/tracing/trace_listener.py	Imports the new event types and registers event-bus handlers that forward conversation events into the trace pipeline with corresponding trace event type strings.
Conversational mixin event emission lib/crewai/src/crewai/experimental/conversational_mixin.py	route_conversation(), append_assistant_message(), and conversational receive_user_message() now emit conversation_route_selected and conversation_message_added events via helper publish methods including session id and message indices.
Flow deferred trace finalization lib/crewai/src/crewai/flow/runtime.py	Adds Flow._deferred_flow_started_event_id and refactors kickoff_async() to defer, stash, restore, or emit FlowStartedEvent based on trace finalization settings, ensuring correct parent trace scope for conversational turns.
Conversational event emission and deferred tracing tests lib/crewai/tests/test_flow_conversation.py	New tests assert user/assistant message-added events and a single route-selected event per turn, and verify a single session-level FlowStartedEvent when defer_trace_finalization=True across multiple turns.

Sequence Diagram

sequenceDiagram
  participant ConversationalMixin
  participant EventBus
  participant TraceListener
  participant Flow
  ConversationalMixin->>EventBus: emit conversation_message_added (user, session_id, message_index)
  EventBus->>TraceListener: forward conversation_message_added -> _handle_action_event
  ConversationalMixin->>EventBus: emit conversation_route_selected (route, previous_intent, session_id)
  EventBus->>TraceListener: forward conversation_route_selected -> _handle_action_event
  ConversationalMixin->>EventBus: emit conversation_message_added (assistant, session_id, message_index)
  EventBus->>TraceListener: forward conversation_message_added -> _handle_action_event
  Flow->>Flow: kickoff_async() (may restore deferred FlowStartedEvent scope)

Loading

Estimated code review effort

🎯 4 (Complex) | ⏱️ ~60 minutes

Possibly related PRs

• crewAIInc/crewAI#6034: Overlapping conversational tracing changes and defer_trace_finalization usage in the conversational REPL flow.

Suggested reviewers

• vinibrsl

Poem

🐰 Whiskers twitch as events take flight,
Messages tracked by day and night,
Routes chosen, traces softly keyed,
One session start for every creed,
Hops of logs in tidy light.

🚥 Pre-merge checks | ✅ 3 | ❌ 2

❌ Failed checks (1 warning, 1 inconclusive)

Check name	Status	Explanation	Resolution
Docstring Coverage	⚠️ Warning	Docstring coverage is 44.00% which is insufficient. The required threshold is 80.00%.	Write docstrings for the functions missing them to satisfy the coverage threshold.
Title check	❓ Inconclusive	The title 'Lorenze/imp/conversational flow traces' is partially related to the changeset but is vague and uses a branch naming convention rather than a clear, descriptive summary of the main change.	Revise the title to be more descriptive and specific, such as 'Add observability for conversational flows with new event types' or 'Implement conversation message and route selection events for flow tracing'.

✅ Passed checks (3 passed)

Check name	Status	Explanation
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/imp/conversational-flow-traces

---

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 and usage tips.}

[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/events/listeners/tracing/trace_listener.py`:
- Around line 260-270: Conversation events (ConversationMessageAddedEvent and
ConversationRouteSelectedEvent) may arrive before FlowStartedEvent creates the
tracing batch, so update the on_conversation_message_added and
on_conversation_route_selected handlers to ensure the trace batch is initialized
before calling _handle_trace_event; specifically, call the same batch
initialization logic used for FlowStartedEvent (or extract that logic into a
helper like _ensure_trace_batch_exists and invoke it here), falling back to
creating a batch from the event’s flow/run identifiers if needed, then proceed
to call
self._handle_trace_event("conversation_message_added"/"conversation_route_selected",
source, event).

In `@lib/crewai/src/crewai/experimental/conversational_mixin.py`:
- Around line 482-483: The code sets message_index using max(len(state.messages)
- 1, 0), which yields 0 for empty transcripts and may point to a non-existent
message; change this to emit None when state.messages is empty (e.g.,
message_index = (len(state.messages) - 1) if state.messages else None) in the
place where message_index is set (the conversational mixin method that builds
the event/state using state.messages and previous_intent in ConversationalMixin
/ conversational_mixin.py).

🪄 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: 1de92f62-edb3-4176-84d8-16823a68fecc

📥 Commits

Reviewing files that changed from the base of the PR and between 14ce97d and e1ecaa3.

📒 Files selected for processing (7)

• lib/crewai/src/crewai/events/__init__.py
• lib/crewai/src/crewai/events/event_types.py
• lib/crewai/src/crewai/events/listeners/tracing/trace_listener.py
• lib/crewai/src/crewai/events/types/flow_events.py
• lib/crewai/src/crewai/experimental/conversational_mixin.py
• lib/crewai/src/crewai/flow/runtime.py
• lib/crewai/tests/test_flow_conversation.py

[cursor]

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

There are 2 total unresolved issues (including 1 from previous review).

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

^{Reviewed by Cursor Bugbot for commit 5fbcbe0. Configure here.}