docs: clarify RunResult testing surface

livekit-agents/livekit/agents/voice/agent_session.py

@@ -536,6 +536,16 @@ def run(
         input_modality: Literal["text", "audio"] = "text",
         output_type: type[Run_T] | None = None,
     ) -> RunResult[Run_T]:
+        """Run a single user turn and capture its testing result surface.
+
+        The returned `RunResult` is meant for tests and deterministic external
+        consumers. In most cases, `RunResult.events` should be treated as the primary
+        seam: it records typed events in chronological order and is usually sufficient
+        without depending on broader runtime or observability surfaces.
+
+        `RunResult.final_output` can be useful when an agent naturally produces one,
+        but it is optional and should be treated as a secondary convenience.
+        """
         if self._global_run_state is not None and not self._global_run_state.done():
             raise RuntimeError("nested runs are not supported")
 

livekit-agents/livekit/agents/voice/run_result.py

@@ -79,7 +79,16 @@ def __init__(self, *, user_input: str | None = None, output_type: type[Run_T] |
 
     @property
     def events(self) -> list[RunEvent]:
-        """List of all recorded events generated during the run."""
+        """List of recorded events generated during the run.
+
+        This is the primary testing-facing surface for inspecting what happened in a
+        run. Events are kept in chronological order and contain typed items such as
+        message, function_call, function_call_output, and agent_handoff.
+
+        For most external consumers, `events` is the smallest honest seam to depend
+        on. It intentionally avoids exposing broader session analytics, room state,
+        transcripts, or raw audio payloads.
+        """
         return self._recorded_items
 
     @functools.cached_property
@@ -107,6 +116,11 @@ def final_output(self) -> Run_T:
         """
         Returns the final output of the run after completion.
 
+        `final_output` is optional and may not be present for every run shape.
+        External consumers that want a stable, minimal result surface should prefer
+        `events` first and only read `final_output` when it is naturally produced by
+        the agent under test.
+
         Raises:
             RuntimeError: If the run is not complete or no output is set.