profiling: added implementation as plugin for dev install

Author: yarikdevcom

.gitignore

@@ -84,3 +84,6 @@ stream-py/
 # Artifacts / assets
 *.pt
 *.kef
+
+# opencode
+/opencode.json

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

@@ -39,6 +39,7 @@
 from ..vad.events import VADAudioEvent
 from . import events
 from .conversation import Conversation
+from ..profiling import Profiler
 
 if TYPE_CHECKING:
     from vision_agents.plugins.getstream.stream_edge_transport import StreamEdge
@@ -103,6 +104,7 @@ def __init__(
         # MCP servers for external tool and resource access
         mcp_servers: Optional[List[MCPBaseServer]] = None,
         tracer: Tracer = trace.get_tracer("agents"),
+        profiler: Optional[Profiler] = None,
     ):
         self.instructions = instructions
         self.edge = edge
@@ -146,7 +148,7 @@ def __init__(
         self._pending_user_transcripts: Dict[str, str] = {}
 
         # Merge plugin events BEFORE subscribing to any events
-        for plugin in [stt, tts, turn_detection, vad, llm, edge]:
+        for plugin in [stt, tts, turn_detection, vad, llm, edge, profiler]:
             if plugin and hasattr(plugin, "events"):
                 self.logger.info(f"Registered plugin {plugin}")
                 self.events.merge(plugin.events)
@@ -177,6 +179,8 @@ def __init__(
         self._setup_stt()
         self._setup_turn_detection()
 
+        self.events.send(events.AgentInitEvent())
+
     async def simple_response(
         self, text: str, participant: Optional[Participant] = None
     ) -> None:
@@ -441,6 +445,8 @@ async def on_ended(event: CallEndedEvent):
         except asyncio.CancelledError:
             running_event.clear()
 
+        self.events.send(events.AgentFinishEvent())
+
         await asyncio.shield(self.close())
 
     async def close(self):

agents-core/vision_agents/core/agents/events.py

@@ -3,6 +3,20 @@
 from typing import Optional, Any, Dict
 
 
+@dataclass
+class AgentInitEvent(BaseEvent):
+    """Event emitted when Agent class initialized."""
+
+    type: str = field(default="agent.init", init=False)
+
+
+@dataclass
+class AgentFinishEvent(BaseEvent):
+    """Event emitted when agent.finish() call ended."""
+
+    type: str = field(default="agent.finish", init=False)
+
+
 @dataclass
 class AgentSayEvent(PluginBaseEvent):
     """Event emitted when the agent wants to say something."""

agents-core/vision_agents/core/profiling/__init__.py

@@ -0,0 +1,3 @@
+from .base import Profiler
+
+__all__ = ["Profiler"]

agents-core/vision_agents/core/profiling/base.py

@@ -0,0 +1,27 @@
+import pyinstrument
+
+import logging
+
+from vision_agents.core.events import EventManager
+from vision_agents.core.agents import events
+
+logger = logging.getLogger(__name__)
+
+
+class Profiler:
+    def __init__(self, output_path='./profile.html'):
+        self.output_path = output_path
+        self.events = EventManager()
+        self.profiler = pyinstrument.Profiler()
+        self.events.subscribe(self.on_start)
+        self.events.subscribe(self.on_finish)
+
+    def on_start(self, event: events.AgentInitEvent):
+        logger.info("Profiler started.")
+        self.profiler.start()
+
+    def on_finish(self, event: events.AgentFinishEvent):
+        self.profiler.stop()
+        logger.info(f"Profiler stopped. Time file saved at: {self.output_path}")
+        with open(self.output_path, 'w') as f:
+            f.write(self.profiler.output_html())

examples/01_simple_agent_example/simple_agent_example.py

@@ -1,17 +1,15 @@
 import asyncio
 from uuid import uuid4
 from dotenv import load_dotenv
-import pyinstrument
 
 from vision_agents.core import User, Agent
+from vision_agents.core.profiling import Profiler
 from vision_agents.plugins import cartesia, deepgram, getstream, gemini
 
 load_dotenv()
 
 
 async def start_agent() -> None:
-    profiler = pyinstrument.Profiler()
-    profiler.start()
     llm = gemini.LLM("gemini-2.0-flash")
     # create an agent to run with Stream's edge, openAI llm
     agent = Agent(
@@ -25,6 +23,7 @@ async def start_agent() -> None:
         llm=llm,
         tts=cartesia.TTS(),
         stt=deepgram.STT(),
+        profiler=Profiler(),
         # vad=silero.VAD(),
         # realtime version (vad, tts and stt not needed)
         # llm=openai.Realtime()
@@ -59,10 +58,5 @@ async def start_agent() -> None:
         # run till the call ends
         await agent.finish()
 
-    profiler.stop()
-    with open('profiled.html', 'w') as f:
-        f.write(profiler.output_html())
-
-
 if __name__ == "__main__":
     asyncio.run(start_agent())

pyproject.toml

@@ -75,6 +75,7 @@ dev = [
     "pytest-timeout>=2.4.0",
     "hatch-vcs>=0.5.0",
     "hatch>=1.14.2",
+    "pyinstrument>=5.1.1",
 ]
 
 [tool.mypy]