feat(voice): expose item_id on UserInputTranscribedEvent (closes #6109)

[tsushanth]

Why

Closes #6109.

`AgentSession`'s `user_input_transcribed` event fires once per interim transcript on realtime models — every streamed delta produces a new `is_final=False` event, so a single user utterance produces many events with no stable correlation key. The internal `llm.InputTranscriptionCompleted` already carries an `item_id` that uniquely identifies the utterance, but when `AgentActivity._on_input_audio_transcription_completed` re-emits it upward as `UserInputTranscribedEvent`, the id is dropped on the floor:

```python

livekit-agents/livekit/agents/voice/agent_activity.py — before

def _on_input_audio_transcription_completed(self, ev: llm.InputTranscriptionCompleted) -> None:
self._session._user_input_transcribed(
UserInputTranscribedEvent(transcript=ev.transcript, is_final=ev.is_final)
) # ev.item_id is dropped
```

Consequence: consumers that need per-utterance dedup — e.g. "notify the frontend 'user speech received' so it renders a placeholder exactly once" — must either keep manual `last_item_id` state the event can't actually provide, or bypass the provider-agnostic event entirely and read `item_id` from `openai_server_event_received`. That escape hatch isn't portable: Gemini's realtime plugin doesn't emit `openai_server_event_received` at all.

Fix

Add `item_id: str | None = None` to `UserInputTranscribedEvent` and thread it through the realtime emission site:

```python

livekit-agents/livekit/agents/voice/events.py — added field

class UserInputTranscribedEvent(BaseModel):
...
item_id: str | None = None
"""Stable id identifying the user utterance this transcript belongs to. On
realtime models, every interim and final UserInputTranscribedEvent for a
single utterance shares the same item_id, so consumers can dedup interim
transcripts and react exactly once per utterance using the provider-agnostic
event surface. None on STT paths where no upstream item id exists."""
```

```python

livekit-agents/livekit/agents/voice/agent_activity.py — threaded through

def _on_input_audio_transcription_completed(self, ev: llm.InputTranscriptionCompleted) -> None:
self._session._user_input_transcribed(
UserInputTranscribedEvent(
transcript=ev.transcript, is_final=ev.is_final, item_id=ev.item_id
)
)
```

STT paths (`on_interim_transcript` / `on_final_transcript` in the same file) leave `item_id` at the default `None` because the STT layer has no corresponding upstream id concept. Existing subscribers reading `transcript` / `is_final` / `language` / `speaker_id` / `created_at` see no behavioral change.

Test

New `tests/test_user_input_transcribed_event.py` (4 unit tests):

• `test_user_input_transcribed_event_carries_item_id` — schema accepts the field
• `test_user_input_transcribed_event_item_id_defaults_to_none` — backwards-compat for STT paths
• `test_user_input_transcribed_event_serialises_item_id` — `model_dump` includes the field (relevant for the cross-process host transport already exercised in `test_session_host.py`)
• `test_input_transcription_completed_item_id_can_thread_to_event` — pins the realtime data flow without instantiating the full `AgentActivity` (Pydantic schema contract is the boundary under test)

All four fail on unpatched source because Pydantic rejects the unknown `item_id` kwarg.

```
$ uv run pytest tests/test_user_input_transcribed_event.py --unit -v
PASSED tests/test_user_input_transcribed_event.py::test_user_input_transcribed_event_carries_item_id
PASSED tests/test_user_input_transcribed_event.py::test_user_input_transcribed_event_item_id_defaults_to_none
PASSED tests/test_user_input_transcribed_event.py::test_user_input_transcribed_event_serialises_item_id
PASSED tests/test_user_input_transcribed_event.py::test_input_transcription_completed_item_id_can_thread_to_event
4 passed in 0.05s
```

Backwards compatibility

Strict additive change. `item_id` is optional and defaults to `None`, so:

• Existing call sites that construct `UserInputTranscribedEvent` without `item_id` continue to work (verified in the test where the STT-style construction without `item_id` round-trips with `item_id=None`)
• Existing subscribers that don't read `item_id` see no behavioral change
• The new field surfaces via the existing event surface, so no new event-name registration is needed downstream

[devin-ai-integration]

Devin Review found 1 potential issue.

[devin-ai-integration]

🚩 Remote session transport does not forward item_id

The _on_user_input_transcribed handler in livekit-agents/livekit/agents/voice/remote_session.py:466-474 constructs the protobuf UserInputTranscribed message with only transcript and is_final — the new item_id field is not forwarded. This means remote session consumers won't receive the item_id for dedup purposes. This is not a regression (the protobuf schema would need a separate update), but it limits the utility of the feature for remote/distributed deployments.

---

Was this helpful? React with 👍 or 👎 to provide feedback.

[tsushanth]

Thanks @devin-ai-integration — good catch and you're right that this is a separate concern from the local-event change.

As you noted, propagating item_id to remote-session consumers requires a protobuf schema update (UserInputTranscribed would need a new field) plus the corresponding _on_user_input_transcribed forwarding in remote_session.py:466-474. Both go beyond the scope of #6109 (which is about exposing item_id on the local Python event for in-process dedup).

Happy to:

• Leave it as a follow-up issue ("expose item_id over the remote-session wire") so it can be co-ordinated with whatever proto-version bump cycle the team prefers, or
• Tack the proto + transport changes onto this PR if a maintainer would rather land them together.

Let me know which fits the release plan better.