Ensure user agent is initialized before joining the call

[tbarbugli]

Make sure the user agent is created when joining the call (one can still do agent.create_user() before that but it is no longer necessary).

When the user agent is not populated, you can get weird warnings from audio track subscriptions like this one:

ERROR:vision_agents.core.events.manager:[call:496ee31e-a277-48ea-af0c-4568bbc4bb9d] Error calling handler _on_track_published from vision_agents.plugins.getstream.stream_edge_transport for event stream.video.sfu.event.TrackPublished
Traceback (most recent call last):
  File “/Users/tommaso/src/Vision-Agents/agents-core/vision_agents/core/events/manager.py”, line 503, in _run_handler
    return await handler(event)
           ^^^^^^^^^^^^^^^^^^^^
  File “/Users/tommaso/src/Vision-Agents/plugins/getstream/vision_agents/plugins/getstream/stream_edge_transport.py”, line 167, in _on_track_published
    raise TimeoutError(
TimeoutError: Timeout waiting for pending track: 1 (audio) from user 1bde1734-e6ef-4a50-b676-a0f006859073, session 687890fd-038e-4a65-ba5c-4bd1e9793c0d. Waited 10.0s but WebRTC track_added with matching kind was never received.Pending tracks: {}

Summary by CodeRabbit

• Refactor

  • Agents now initialize their user automatically during join, removing the need for explicit user-creation steps in example setups; initialization is guarded to avoid duplicate creation.

• Style

  • Consistent quoting and minor logging/string formatting updated across the codebase for readability.

[coderabbitai]

Walkthrough

Agent user creation is made idempotent via a new _agent_user_initialized flag; Agent.join() now calls create_user() early. Examples removing explicit await agent.create_user() are updated. Minor style/quote normalizations applied in the event manager.

Changes

Cohort / File(s)	Summary
Core Agent Initialization agents-core/vision_agents/core/agents/agents.py	Adds _agent_user_initialized flag; changes create_user signature to async def create_user(self) -> None, makes it idempotent (early return when initialized), sets a default agent_user.id when missing, calls edge.create_user, and has join() call create_user() at start. Minor docstring/comment edits.
Event Manager Style Consistency agents-core/vision_agents/core/events/manager.py	Normalizes quoting (single → double) and minor spacing; updates type-annotation quoting in merge() and default string quoting in register_events_from_module(). No runtime behavioral changes.
Example Code Updates examples/01_simple_agent_example/simple_agent_example.py, examples/02_golf_coach_example/golf_coach_example.py, examples/other_examples/09_github_mcp_demo/...	Removes explicit await agent.create_user() calls across examples; inlines or passes User/Edge into Agent where applicable and adds User import where needed. Demo flows otherwise unchanged.

Sequence Diagram(s)

sequenceDiagram
    actor Runner
    participant Example
    participant Agent
    participant Edge

    rect rgb(200,220,240)
    Note over Example,Agent: Previous flow (explicit create_user)
    Runner->>Example: run example
    Example->>Agent: instantiate Agent(agent_user?, edge)
    Example->>Agent: await agent.create_user()
    Agent->>Edge: create user request
    Edge-->>Agent: user created
    Example->>Agent: await agent.join(call)
    Agent-->>Example: joined
    end

    rect rgb(220,240,200)
    Note over Example,Agent: New flow (implicit, idempotent)
    Runner->>Example: run example
    Example->>Agent: instantiate Agent(agent_user?, edge)
    Example->>Agent: await agent.join(call)
    Agent->>Agent: create_user() [guarded by _agent_user_initialized]
    Agent->>Edge: create user request (if needed)
    Edge-->>Agent: user created
    Agent-->>Example: joined
    end

Loading

Estimated code review effort

🎯 2 (Simple) | ⏱️ ~10 minutes

Possibly related PRs

• fix: fixed examples #83 — similar changes removing/preventing pre-join agent user creation and moving user creation into the join flow.
• Join call latency #63 — also modifies Agent.join() and related join/user-creation sequencing.

Suggested reviewers

• dangusev

Poem

I mapped the quiet socket of a name, small as a secret;
the agent sleeps in its headroom, a stitched-in zero,
the id appears like a cameo in the dark — agent-{uuid}.
We removed the extra knocking; the join breathes inward.
The examples learn to wait for the house to open.

Pre-merge checks and finishing touches

❌ Failed checks (1 warning)

Check name	Status	Explanation	Resolution
Docstring Coverage	⚠️ Warning	Docstring coverage is 40.00% which is insufficient. The required threshold is 80.00%.	You can run @coderabbitai generate docstrings to improve docstring coverage.

✅ Passed checks (2 passed)

Check name	Status	Explanation
Description Check	✅ Passed	Check skipped - CodeRabbit’s high-level summary is enabled.
Title Check	✅ Passed	The PR title "Ensure user agent is initialized before joining the call" directly and accurately reflects the main change in the changeset. The core modification adds an initialization flag (_agent_user_initialized) to the Agent class, makes create_user() idempotent, and ensures create_user() is called at the start of join() to address a race condition. The title is concise, clear, and specific enough that a teammate reviewing the commit history would immediately understand the primary change—that user agent initialization now happens automatically during the join operation rather than requiring a separate manual step. The title avoids vague terms and generic phrasing, instead using descriptive language that captures the intent of the change.

✨ Finishing touches

• 📝 Generate docstrings

🧪 Generate unit tests (beta)

• Create PR with unit tests
• Post copyable unit tests in a comment
• Commit unit tests in branch fix-warning-from-race

---

📜 Recent review details

Configuration used: Path: .coderabbit.yaml

Review profile: CHILL

Plan: Pro

Disabled knowledge base sources:

• Linear integration is disabled by default for public repositories

You can enable these sources in your CodeRabbit configuration.

📥 Commits

Reviewing files that changed from the base of the PR and between ac0bd87 and 377e759.

📒 Files selected for processing (4)

• agents-core/vision_agents/core/agents/agents.py (4 hunks)
• examples/other_examples/09_github_mcp_demo/gemini_realtime_github_mcp_demo.py (1 hunks)
• examples/other_examples/09_github_mcp_demo/github_mcp_demo.py (0 hunks)
• examples/other_examples/09_github_mcp_demo/openai_realtime_github_mcp_demo.py (0 hunks)

💤 Files with no reviewable changes (2)

• examples/other_examples/09_github_mcp_demo/openai_realtime_github_mcp_demo.py
• examples/other_examples/09_github_mcp_demo/github_mcp_demo.py

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

• agents-core/vision_agents/core/agents/agents.py

🧰 Additional context used

📓 Path-based instructions (1)

**/*.py

📄 CodeRabbit inference engine (.cursor/rules/python.mdc)

**/*.py: Do not modify sys.path in Python code
Docstrings must follow the Google style guide

Files:

• examples/other_examples/09_github_mcp_demo/gemini_realtime_github_mcp_demo.py

🧬 Code graph analysis (1)

examples/other_examples/09_github_mcp_demo/gemini_realtime_github_mcp_demo.py (1)

agents-core/vision_agents/core/edge/types.py (1)

• User (15-18)

⏰ Context from checks skipped due to timeout of 90000ms. You can increase the timeout in your CodeRabbit configuration to a maximum of 15 minutes (900000ms). (3)

• GitHub Check: unit / Ruff & mypy
• GitHub Check: unit / Test "not integration"
• GitHub Check: unit / Ruff & mypy

🔇 Additional comments (1)

examples/other_examples/09_github_mcp_demo/gemini_realtime_github_mcp_demo.py (1)

60-67: LGTM! Clean refactor aligns with race condition fix.

The inline initialization of edge and agent_user at Agent construction is correct and aligns with the PR's objective to eliminate the race condition. By providing the user upfront, the automatic initialization during join() (line 93) ensures the user agent is properly populated before audio track subscriptions occur, preventing the TimeoutError described in the PR.

---

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

Caution

Some comments are outside the diff and can’t be posted inline due to platform limitations.

⚠️ Outside diff range comments (3)

agents-core/vision_agents/core/agents/agents.py (3)

244-246: Duplicate coordinator wildcard subscriptions cause double event delivery.

_on_wildcard("*", ...) is registered twice on _coordinator_ws_client. Remove the second block.

-            connection._connection._coordinator_ws_client.on_wildcard(
-                "*",
-                lambda event_name, event: self.events.send(event),
-            )

Also applies to: 258-261

---

47-52: Treat CancelledError as normal in background task logging.

Cancelled tasks during shutdown shouldn’t log as errors.

 def _log_task_exception(task: asyncio.Task):
     try:
         task.result()
+    except asyncio.CancelledError:
+        return
     except Exception:
         logger.exception("Error in background task")

---

686-723: _process_track loop lacks cancellation handling; cleanup log is unreachable.

Add CancelledError handling and move summary to finally to guarantee execution.

-        while True:
-            try:
-                # Use the raw forwarder instead of competing for track.recv()
-                video_frame = await raw_forwarder.next_frame(timeout=2.0)
+        try:
+            while True:
+                # Use the raw forwarder instead of competing for track.recv()
+                video_frame = await raw_forwarder.next_frame(timeout=2.0)
                 ...
-            except asyncio.TimeoutError:
+            except asyncio.TimeoutError:
                 ...
-        # Cleanup and logging
-        self.logger.info(
-            f"🎥VDP: Video processing loop ended for track {track_id} - timeouts: {timeout_errors}, consecutive_errors: {consecutive_errors}"
-        )
+        except asyncio.CancelledError:
+            pass
+        finally:
+            # Cleanup and logging
+            self.logger.info(
+                f"🎥VDP: Video processing loop ended for track {track_id} - timeouts: {timeout_errors}, consecutive_errors: {consecutive_errors}"
+            )

🧹 Nitpick comments (7)

examples/other_examples/09_github_mcp_demo/gemini_realtime_github_mcp_demo.py (1)

72-75: Remove redundant agent.create_user(); join() now does it.

join() calls create_user internally. Keeping this explicit call risks double-creation until idempotency is fixed in core. Drop it.

-        # Create the agent user
-        await agent.create_user()

examples/other_examples/gemini_live_realtime/gemini_live_example.py (1)

21-36: Use agent.edge.client for the Call to avoid config drift.

You construct a separate AsyncStream client; prefer agent.edge.client for region/auth consistency.

-    client = AsyncStream()
-    call = client.video.call("default", str(uuid4()))
+    call = getstream.Edge().client.video.call("default", str(uuid4()))

examples/02_golf_coach_example/golf_coach_example.py (1)

27-33: Open demo timing is fine; keep consistent across examples.

This opens inside the join context; other examples do it before join. Consider standardizing for docs clarity.

examples/01_simple_agent_example/simple_agent_example.py (1)

33-38: Demo UI open-before-join differs from other examples.

Both orders work; consider using one pattern repo-wide to reduce confusion.

agents-core/vision_agents/core/agents/agents.py (3)

661-676: Variable naming typo: hasImageProcessers → has_image_processors.

Minor readability fix; update all references.

-        hasImageProcessers = len(self.image_processors) > 0
+        has_image_processors = len(self.image_processors) > 0
 ...
-        if not hasImageProcessers:
+        if not has_image_processors:
 ...
-                    if hasImageProcessers:
+                    if has_image_processors:

Also applies to: 696-706

---

162-166: Initialize _video_forwarders in init to avoid hasattr checks.

Define once; then drop hasattr conditionals.

@@
-        self._track_tasks: Dict[str, asyncio.Task] = {}
+        self._track_tasks: Dict[str, asyncio.Task] = {}
+        self._video_forwarders: list = []
@@
-        # Stop all video forwarders
-        if hasattr(self, "_video_forwarders"):
+        # Stop all video forwarders
             for forwarder in self._video_forwarders:
                 try:
                     await forwarder.stop()
                 except Exception as e:
                     self.logger.error(f"Error stopping video forwarder: {e}")
             self._video_forwarders.clear()
@@
-        if not hasattr(self, "_video_forwarders"):
-            self._video_forwarders = []
         self._video_forwarders.append(raw_forwarder)

Also applies to: 322-329, 627-630

---

112-113: Optional: refresh logger name after assigning auto id.

Logger includes agent_user.id set post-init; consider updating logger to include the final id for clearer logs.

@@ async def create_user(self) -> None:
-            if not self.agent_user.id:
-                self.agent_user.id = f"agent-{uuid4()}"
+            if not self.agent_user.id:
+                self.agent_user.id = f"agent-{uuid4()}"
+                # Recreate logger with stable id
+                self.logger = logging.getLogger(f"Agent[{self.agent_user.id}]")

Also applies to: 399-401

📜 Review details

Configuration used: Path: .coderabbit.yaml

Review profile: CHILL

Plan: Pro

Disabled knowledge base sources:

• Linear integration is disabled by default for public repositories

You can enable these sources in your CodeRabbit configuration.

📥 Commits

Reviewing files that changed from the base of the PR and between 1025a42 and c09e360.

📒 Files selected for processing (6)

• agents-core/vision_agents/core/agents/agents.py (21 hunks)
• agents-core/vision_agents/core/events/manager.py (15 hunks)
• examples/01_simple_agent_example/simple_agent_example.py (2 hunks)
• examples/02_golf_coach_example/golf_coach_example.py (1 hunks)
• examples/other_examples/09_github_mcp_demo/gemini_realtime_github_mcp_demo.py (1 hunks)
• examples/other_examples/gemini_live_realtime/gemini_live_example.py (1 hunks)

🧰 Additional context used

📓 Path-based instructions (1)

**/*.py

📄 CodeRabbit inference engine (.cursor/rules/python.mdc)

**/*.py: Never adjust sys.path (e.g., sys.path.append/insert/assignment)
Docstrings must follow the Google style guide

Files:

• examples/other_examples/gemini_live_realtime/gemini_live_example.py
• examples/other_examples/09_github_mcp_demo/gemini_realtime_github_mcp_demo.py
• examples/01_simple_agent_example/simple_agent_example.py
• examples/02_golf_coach_example/golf_coach_example.py
• agents-core/vision_agents/core/agents/agents.py
• agents-core/vision_agents/core/events/manager.py

🧬 Code graph analysis (6)

examples/other_examples/gemini_live_realtime/gemini_live_example.py (1)

agents-core/vision_agents/core/edge/types.py (1)

• User (15-18)

examples/other_examples/09_github_mcp_demo/gemini_realtime_github_mcp_demo.py (1)

agents-core/vision_agents/core/edge/types.py (1)

• User (15-18)

examples/01_simple_agent_example/simple_agent_example.py (1)

agents-core/vision_agents/core/agents/agents.py (1)

• Agent (54-1045)

examples/02_golf_coach_example/golf_coach_example.py (1)

agents-core/vision_agents/core/agents/agents.py (1)

• join (203-276)

agents-core/vision_agents/core/agents/agents.py (8)

agents-core/vision_agents/core/mcp/mcp_manager.py (1)

• MCPManager (9-147)

agents-core/vision_agents/core/agents/conversation.py (1)

• StreamHandle (37-57)

plugins/getstream/vision_agents/plugins/getstream/stream_edge_transport.py (1)

• create_user (238-240)

agents-core/vision_agents/core/events/manager.py (1)

• send (426-468)

agents-core/vision_agents/core/agents/events.py (1)

• AgentSayEvent (7-16)

agents-core/vision_agents/core/utils/video_forwarder.py (1)

• VideoForwarder (13-188)

plugins/gemini/vision_agents/plugins/gemini/gemini_realtime.py (2)

• _watch_video_track (281-320)
• simple_response (88-99)

agents-core/vision_agents/core/turn_detection/events.py (2)

• TurnStartedEvent (10-25)
• TurnEndedEvent (29-44)

agents-core/vision_agents/core/events/manager.py (1)

agents-core/vision_agents/core/edge/sfu_events.py (17)

• name (1935-1939)
• from_proto (36-43)
• from_proto (53-61)
• from_proto (72-81)
• from_proto (92-101)
• from_proto (113-123)
• from_proto (132-139)
• from_proto (153-161)
• from_proto (175-183)
• from_proto (193-201)
• from_proto (226-244)
• from_proto (253-260)
• from_proto (269-276)
• from_proto (296-310)
• from_proto (325-334)
• from_proto (347-354)
• from_proto (375-390)

⏰ Context from checks skipped due to timeout of 90000ms. You can increase the timeout in your CodeRabbit configuration to a maximum of 15 minutes (900000ms). (3)

• GitHub Check: unit / Test "not integration"
• GitHub Check: unit / Ruff & mypy
• GitHub Check: unit / Ruff & mypy

🔇 Additional comments (4)

examples/02_golf_coach_example/golf_coach_example.py (1)

14-22: Good alignment with auto user initialization.

Passing User to Agent and relying on join() for creation is correct. No issues spotted.

examples/01_simple_agent_example/simple_agent_example.py (1)

16-19: Inline agent_user + removed create_user — LGTM.

Matches the new lifecycle. No functional concerns.

examples/other_examples/gemini_live_realtime/gemini_live_example.py (1)

14-17: The logging setup is safe. The custom factory is auto-installed when Agent is imported.

When gemini_live_example.py imports Agent from vision_agents.core.agents, it triggers the import of logging_utils, which runs module-level code that installs the custom log record factory via logging.setLogRecordFactory(_contextual_record_factory).

This factory always adds a call_id attribute to every log record—defaulting to "-" if no call context is set. Therefore, the %(call_id)s format string will never raise a KeyError.

agents-core/vision_agents/core/events/manager.py (1)

1-547: LGTM! Formatting and style updates look good.

The changes in this file are purely cosmetic—standardizing quote usage (single to double) and adjusting spacing for consistency. No behavioral changes or logic modifications are introduced. These updates improve code uniformity without affecting functionality.