feat: add custom events and metrics broadcasting via Stream Video

[d3xvn]

Add ability to send custom events and metrics to call participants through Stream Video's custom events API. This enables building real-time dashboards in client apps.

• Add send_custom_event() to EdgeTransport and StreamEdge
• Add send_custom_event() and send_metrics_event() to Agent
• Add broadcast_metrics and broadcast_metrics_interval constructor params for automatic periodic metrics broadcasting
• Store Call reference in StreamEdge for event sending

Summary by CodeRabbit

Release Notes

• New Features

  • Agents can now broadcast performance metrics to call participants with configurable intervals.
  • Added public APIs for sending custom events and metric snapshots to all connected participants.
  • New configuration options to enable metrics broadcasting and control broadcast frequency.

• Tests

  • Added comprehensive test coverage for metrics broadcasting and custom event functionality.

_{✏️ Tip: You can customize this high-level summary in your review settings.}

[coderabbitai]

Warning

Rate limit exceeded

@d3xvn has exceeded the limit for the number of commits that can be reviewed per hour. Please wait 17 minutes and 43 seconds before requesting another review.

⌛ How to resolve this issue?

After the wait time has elapsed, a review can be triggered using the @coderabbitai review command as a PR comment. Alternatively, push new commits to this PR.

We recommend that you space out your commits to avoid hitting the rate limit.

🚦 How do rate limits work?

CodeRabbit enforces hourly rate limits for each developer per organization.

Our paid plans have higher rate limits than the trial, open-source and free plans. In all cases, we re-allow further reviews after a brief timeout.

Please see our FAQ for further information.

📝 Walkthrough

Walkthrough

This PR introduces metrics broadcasting functionality enabling agents to periodically emit performance metrics to call participants via custom events. Implementation spans a new abstract interface in EdgeTransport, concrete support in StreamEdge, background task lifecycle management in Agent, and comprehensive test coverage.

Changes

Cohort / File(s)	Summary
Core Agent Metrics Broadcasting agents-core/vision_agents/core/agents/agents.py	Added broadcast_metrics and broadcast_metrics_interval configuration options to Agent.__init__. Implemented send_custom_event() and send_metrics_event() public methods. Introduced _metrics_broadcast_loop background task for periodic metric emission with proper lifecycle management (started on join, cancelled on close).
Edge Transport Abstraction agents-core/vision_agents/core/edge/edge_transport.py	Added abstract async method send_custom_event(data: dict) to EdgeTransport interface for broadcasting custom events to call participants.
GetStream Transport Implementation plugins/getstream/vision_agents/plugins/getstream/stream_edge_transport.py	Implemented send_custom_event() method via GetStream Call API. Added internal _call reference management initialized on connection and cleared on close for tracking active call context.
Test Coverage tests/test_agents/test_agents.py	Added send_custom_event() stub to DummyEdge. Implemented four test cases: test_send_custom_event, test_send_metrics_event, test_send_metrics_event_with_fields_filter, and test_broadcast_metrics_enabled to verify metrics emission and filtering behavior.

Sequence Diagram

sequenceDiagram
    actor Agent as Agent Instance
    participant EdgeTransport
    participant StreamEdge
    actor CallAPI as GetStream Call API
    actor Participants as Call Participants

    Agent->>Agent: _metrics_broadcast_loop starts<br/>(background task)
    loop Every broadcast_metrics_interval seconds
        Agent->>Agent: send_metrics_event()
        Agent->>Agent: gather current metrics
        Agent->>EdgeTransport: send_custom_event(metrics_data)
        EdgeTransport->>StreamEdge: send_custom_event(metrics_data)
        activate StreamEdge
        StreamEdge->>StreamEdge: validate call connected
        StreamEdge->>CallAPI: call.send_call_event(custom=data)
        deactivate StreamEdge
        CallAPI->>Participants: broadcast custom event
    end
    Agent->>EdgeTransport: on close: cancel broadcast task

Loading

Estimated Code Review Effort

🎯 3 (Moderate) | ⏱️ ~22 minutes

Poem

A loop whispers metrics into the hollow channel,
Fluorescent data pooling at the edges of connection—
each token counted, each broadcast a small confession.
The agent breathes its measurements like stale air,
and somewhere, the Call remembers it was here. 📊

🚥 Pre-merge checks | ✅ 2 | ❌ 1

❌ Failed checks (1 warning)

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

✅ Passed checks (2 passed)

Check name	Status	Explanation
Description Check	✅ Passed	Check skipped - CodeRabbit’s high-level summary is enabled.
Title check	✅ Passed	The title clearly and concisely summarizes the main changes: adding custom events and metrics broadcasting capabilities via Stream Video.

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

---

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

[Nash0x7E2]

@d3xvn - I left a few notes. Once resolved please feel free to test, verify and merge.

[DaemonLoki]

LGTM

Resolved comments