Update agent.py

Author: DanielHashmi

src/agents/realtime/agent.py

@@ -1,11 +1,18 @@
+"""
+Realtime agent module providing RealtimeAgent class with Pydantic validation.
+
+This module implements realtime-specific agent functionality with strong type validation
+and configuration management for voice-enabled agents.
+"""
+
 from __future__ import annotations
 
-import dataclasses
 import inspect
 from collections.abc import Awaitable
-from dataclasses import dataclass, field
 from typing import Any, Callable, Generic, cast
 
+from pydantic import ConfigDict, Field
+
 from ..agent import AgentBase
 from ..handoffs import Handoff
 from ..lifecycle import AgentHooksBase, RunHooksBase
@@ -20,62 +27,70 @@
 """Run hooks for `RealtimeAgent`s."""
 
 
-@dataclass
 class RealtimeAgent(AgentBase, Generic[TContext]):
-    """A specialized agent instance that is meant to be used within a `RealtimeSession` to build
+    """
+    A specialized agent instance that is meant to be used within a `RealtimeSession` to build
     voice agents. Due to the nature of this agent, some configuration options are not supported
-    that are supported by regular `Agent` instances. For example:
-    - `model` choice is not supported, as all RealtimeAgents will be handled by the same model
-      within a `RealtimeSession`.
-    - `modelSettings` is not supported, as all RealtimeAgents will be handled by the same model
-      within a `RealtimeSession`.
-    - `outputType` is not supported, as RealtimeAgents do not support structured outputs.
-    - `toolUseBehavior` is not supported, as all RealtimeAgents will be handled by the same model
-      within a `RealtimeSession`.
-    - `voice` can be configured on an `Agent` level; however, it cannot be changed after the first
-      agent within a `RealtimeSession` has spoken.
-
-    See `AgentBase` for base parameters that are shared with `Agent`s.
+    that are supported by regular `Agent` instances.
+
+    Attributes:
+        instructions: Agent instructions/system prompt
+        handoffs: List of sub-agents for delegation
+        hooks: Lifecycle event callbacks
     """
 
+    model_config = ConfigDict(
+        arbitrary_types_allowed=True,
+        validate_assignment=True,
+        extra="forbid",
+        frozen=True,
+        defer_build=True,
+    )
+
     instructions: (
         str
         | Callable[
             [RunContextWrapper[TContext], RealtimeAgent[TContext]],
             MaybeAwaitable[str],
         ]
         | None
-    ) = None
-    """The instructions for the agent. Will be used as the "system prompt" when this agent is
-    invoked. Describes what the agent should do, and how it responds.
-
-    Can either be a string, or a function that dynamically generates instructions for the agent. If
-    you provide a function, it will be called with the context and the agent instance. It must
-    return a string.
-    """
+    ) = Field(
+        default=None,
+        description="The instructions for the agent. Will be used as the 'system prompt' "
+        "when this agent is invoked.",
+    )
 
-    handoffs: list[RealtimeAgent[Any] | Handoff[TContext, RealtimeAgent[Any]]] = field(
-        default_factory=list
+    handoffs: list[RealtimeAgent[Any] | Handoff[TContext, RealtimeAgent[Any]]] = Field(
+        default_factory=list, description="Handoffs are sub-agents that the agent can delegate to."
     )
-    """Handoffs are sub-agents that the agent can delegate to. You can provide a list of handoffs,
-    and the agent can choose to delegate to them if relevant. Allows for separation of concerns and
-    modularity.
-    """
 
-    hooks: RealtimeAgentHooks | None = None
-    """A class that receives callbacks on various lifecycle events for this agent.
-    """
+    hooks: RealtimeAgentHooks | None = Field(
+        default=None,
+        description="A class that receives callbacks on various lifecycle events for this agent.",
+    )
 
     def clone(self, **kwargs: Any) -> RealtimeAgent[TContext]:
-        """Make a copy of the agent, with the given arguments changed. For example, you could do:
-        ```
-        new_agent = agent.clone(instructions="New instructions")
-        ```
         """
-        return dataclasses.replace(self, **kwargs)
+        Make a copy of the agent, with the given arguments changed.
+
+        Args:
+            **kwargs: Fields to override in the new instance
+
+        Returns:
+            RealtimeAgent[TContext]: New agent instance with specified changes
+        """
+        return self.model_copy(update=kwargs)
 
     async def get_system_prompt(self, run_context: RunContextWrapper[TContext]) -> str | None:
-        """Get the system prompt for the agent."""
+        """
+        Get the system prompt for the agent.
+
+        Args:
+            run_context: Current run context
+
+        Returns:
+            str | None: System prompt if available
+        """
         if isinstance(self.instructions, str):
             return self.instructions
         elif callable(self.instructions):
@@ -87,3 +102,7 @@ async def get_system_prompt(self, run_context: RunContextWrapper[TContext]) -> s
             logger.error(f"Instructions must be a string or a function, got {self.instructions}")
 
         return None
+
+
+# Rebuild models after all definitions
+RealtimeAgent.model_rebuild()