openai-agents 0.0.19__py3-none-any.whl → 0.2.0__py3-none-any.whl

agents/models/chatcmpl_stream_handler.py

@@ -20,21 +20,38 @@ from openai.types.responses import (
     ResponseOutputMessage,
     ResponseOutputRefusal,
     ResponseOutputText,
+    ResponseReasoningItem,
+    ResponseReasoningSummaryPartAddedEvent,
+    ResponseReasoningSummaryPartDoneEvent,
+    ResponseReasoningSummaryTextDeltaEvent,
     ResponseRefusalDeltaEvent,
     ResponseTextDeltaEvent,
     ResponseUsage,
 )
+from openai.types.responses.response_reasoning_item import Summary
+from openai.types.responses.response_reasoning_summary_part_added_event import (
+    Part as AddedEventPart,
+)
+from openai.types.responses.response_reasoning_summary_part_done_event import Part as DoneEventPart
 from openai.types.responses.response_usage import InputTokensDetails, OutputTokensDetails
 
 from ..items import TResponseStreamEvent
 from .fake_id import FAKE_RESPONSES_ID
 
 
+# Define a Part class for internal use
+class Part:
+    def __init__(self, text: str, type: str):
+        self.text = text
+        self.type = type
+
+
 @dataclass
 class StreamingState:
     started: bool = False
     text_content_index_and_output: tuple[int, ResponseOutputText] | None = None
     refusal_content_index_and_output: tuple[int, ResponseOutputRefusal] | None = None
+    reasoning_content_index_and_output: tuple[int, ResponseReasoningItem] | None = None
     function_calls: dict[int, ResponseFunctionToolCall] = field(default_factory=dict)
 
 
@@ -75,12 +92,65 @@ class ChatCmplStreamHandler:
 
             delta = chunk.choices[0].delta
 
-            # Handle text
-            if delta.content:
+            # Handle reasoning content
+            if hasattr(delta, "reasoning_content"):
+                reasoning_content = delta.reasoning_content
+                if reasoning_content and not state.reasoning_content_index_and_output:
+                    state.reasoning_content_index_and_output = (
+                        0,
+                        ResponseReasoningItem(
+                            id=FAKE_RESPONSES_ID,
+                            summary=[Summary(text="", type="summary_text")],
+                            type="reasoning",
+                        ),
+                    )
+                    yield ResponseOutputItemAddedEvent(
+                        item=ResponseReasoningItem(
+                            id=FAKE_RESPONSES_ID,
+                            summary=[Summary(text="", type="summary_text")],
+                            type="reasoning",
+                        ),
+                        output_index=0,
+                        type="response.output_item.added",
+                        sequence_number=sequence_number.get_and_increment(),
+                    )
+
+                    yield ResponseReasoningSummaryPartAddedEvent(
+                        item_id=FAKE_RESPONSES_ID,
+                        output_index=0,
+                        summary_index=0,
+                        part=AddedEventPart(text="", type="summary_text"),
+                        type="response.reasoning_summary_part.added",
+                        sequence_number=sequence_number.get_and_increment(),
+                    )
+
+                if reasoning_content and state.reasoning_content_index_and_output:
+                    yield ResponseReasoningSummaryTextDeltaEvent(
+                        delta=reasoning_content,
+                        item_id=FAKE_RESPONSES_ID,
+                        output_index=0,
+                        summary_index=0,
+                        type="response.reasoning_summary_text.delta",
+                        sequence_number=sequence_number.get_and_increment(),
+                    )
+
+                    # Create a new summary with updated text
+                    current_summary = state.reasoning_content_index_and_output[1].summary[0]
+                    updated_text = current_summary.text + reasoning_content
+                    new_summary = Summary(text=updated_text, type="summary_text")
+                    state.reasoning_content_index_and_output[1].summary[0] = new_summary
+
+            # Handle regular content
+            if delta.content is not None:
                 if not state.text_content_index_and_output:
-                    # Initialize a content tracker for streaming text
+                    content_index = 0
+                    if state.reasoning_content_index_and_output:
+                        content_index += 1
+                    if state.refusal_content_index_and_output:
+                        content_index += 1
+
                     state.text_content_index_and_output = (
-                        0 if not state.refusal_content_index_and_output else 1,
+                        content_index,
                         ResponseOutputText(
                             text="",
                             type="output_text",
@@ -98,14 +168,16 @@ class ChatCmplStreamHandler:
                     # Notify consumers of the start of a new output message + first content part
                     yield ResponseOutputItemAddedEvent(
                         item=assistant_item,
-                        output_index=0,
+                        output_index=state.reasoning_content_index_and_output
+                        is not None,  # fixed 0 -> 0 or 1
                         type="response.output_item.added",
                         sequence_number=sequence_number.get_and_increment(),
                     )
                     yield ResponseContentPartAddedEvent(
                         content_index=state.text_content_index_and_output[0],
                         item_id=FAKE_RESPONSES_ID,
-                        output_index=0,
+                        output_index=state.reasoning_content_index_and_output
+                        is not None,  # fixed 0 -> 0 or 1
                         part=ResponseOutputText(
                             text="",
                             type="output_text",
@@ -119,7 +191,8 @@ class ChatCmplStreamHandler:
                     content_index=state.text_content_index_and_output[0],
                     delta=delta.content,
                     item_id=FAKE_RESPONSES_ID,
-                    output_index=0,
+                    output_index=state.reasoning_content_index_and_output
+                    is not None,  # fixed 0 -> 0 or 1
                     type="response.output_text.delta",
                     sequence_number=sequence_number.get_and_increment(),
                 )
@@ -130,9 +203,14 @@ class ChatCmplStreamHandler:
             # This is always set by the OpenAI API, but not by others e.g. LiteLLM
             if hasattr(delta, "refusal") and delta.refusal:
                 if not state.refusal_content_index_and_output:
-                    # Initialize a content tracker for streaming refusal text
+                    refusal_index = 0
+                    if state.reasoning_content_index_and_output:
+                        refusal_index += 1
+                    if state.text_content_index_and_output:
+                        refusal_index += 1
+
                     state.refusal_content_index_and_output = (
-                        0 if not state.text_content_index_and_output else 1,
+                        refusal_index,
                         ResponseOutputRefusal(refusal="", type="refusal"),
                     )
                     # Start a new assistant message if one doesn't exist yet (in-progress)
@@ -146,14 +224,16 @@ class ChatCmplStreamHandler:
                     # Notify downstream that assistant message + first content part are starting
                     yield ResponseOutputItemAddedEvent(
                         item=assistant_item,
-                        output_index=0,
+                        output_index=state.reasoning_content_index_and_output
+                        is not None,  # fixed 0 -> 0 or 1
                         type="response.output_item.added",
                         sequence_number=sequence_number.get_and_increment(),
                     )
                     yield ResponseContentPartAddedEvent(
                         content_index=state.refusal_content_index_and_output[0],
                         item_id=FAKE_RESPONSES_ID,
-                        output_index=0,
+                        output_index=state.reasoning_content_index_and_output
+                        is not None,  # fixed 0 -> 0 or 1
                         part=ResponseOutputText(
                             text="",
                             type="output_text",
@@ -167,7 +247,8 @@ class ChatCmplStreamHandler:
                     content_index=state.refusal_content_index_and_output[0],
                     delta=delta.refusal,
                     item_id=FAKE_RESPONSES_ID,
-                    output_index=0,
+                    output_index=state.reasoning_content_index_and_output
+                    is not None,  # fixed 0 -> 0 or 1
                     type="response.refusal.delta",
                     sequence_number=sequence_number.get_and_increment(),
                 )
@@ -195,16 +276,39 @@ class ChatCmplStreamHandler:
                     state.function_calls[tc_delta.index].name += (
                         tc_function.name if tc_function else ""
                     ) or ""
-                    state.function_calls[tc_delta.index].call_id += tc_delta.id or ""
+                    state.function_calls[tc_delta.index].call_id = tc_delta.id or ""
+
+        if state.reasoning_content_index_and_output:
+            yield ResponseReasoningSummaryPartDoneEvent(
+                item_id=FAKE_RESPONSES_ID,
+                output_index=0,
+                summary_index=0,
+                part=DoneEventPart(
+                    text=state.reasoning_content_index_and_output[1].summary[0].text,
+                    type="summary_text",
+                ),
+                type="response.reasoning_summary_part.done",
+                sequence_number=sequence_number.get_and_increment(),
+            )
+            yield ResponseOutputItemDoneEvent(
+                item=state.reasoning_content_index_and_output[1],
+                output_index=0,
+                type="response.output_item.done",
+                sequence_number=sequence_number.get_and_increment(),
+            )
 
         function_call_starting_index = 0
+        if state.reasoning_content_index_and_output:
+            function_call_starting_index += 1
+
         if state.text_content_index_and_output:
             function_call_starting_index += 1
             # Send end event for this content part
             yield ResponseContentPartDoneEvent(
                 content_index=state.text_content_index_and_output[0],
                 item_id=FAKE_RESPONSES_ID,
-                output_index=0,
+                output_index=state.reasoning_content_index_and_output
+                is not None,  # fixed 0 -> 0 or 1
                 part=state.text_content_index_and_output[1],
                 type="response.content_part.done",
                 sequence_number=sequence_number.get_and_increment(),
@@ -216,7 +320,8 @@ class ChatCmplStreamHandler:
             yield ResponseContentPartDoneEvent(
                 content_index=state.refusal_content_index_and_output[0],
                 item_id=FAKE_RESPONSES_ID,
-                output_index=0,
+                output_index=state.reasoning_content_index_and_output
+                is not None,  # fixed 0 -> 0 or 1
                 part=state.refusal_content_index_and_output[1],
                 type="response.content_part.done",
                 sequence_number=sequence_number.get_and_increment(),
@@ -261,6 +366,12 @@ class ChatCmplStreamHandler:
 
         # Finally, send the Response completed event
         outputs: list[ResponseOutputItem] = []
+
+        # include Reasoning item if it exists
+        if state.reasoning_content_index_and_output:
+            outputs.append(state.reasoning_content_index_and_output[1])
+
+        # include text or refusal content if they exist
         if state.text_content_index_and_output or state.refusal_content_index_and_output:
             assistant_msg = ResponseOutputMessage(
                 id=FAKE_RESPONSES_ID,
@@ -278,7 +389,8 @@ class ChatCmplStreamHandler:
             # send a ResponseOutputItemDone for the assistant message
             yield ResponseOutputItemDoneEvent(
                 item=assistant_msg,
-                output_index=0,
+                output_index=state.reasoning_content_index_and_output
+                is not None,  # fixed 0 -> 0 or 1
                 type="response.output_item.done",
                 sequence_number=sequence_number.get_and_increment(),
             )

agents/models/openai_chatcompletions.py

@@ -7,7 +7,8 @@ from typing import TYPE_CHECKING, Any, Literal, cast, overload
 
 from openai import NOT_GIVEN, AsyncOpenAI, AsyncStream
 from openai.types import ChatModel
-from openai.types.chat import ChatCompletion, ChatCompletionChunk
+from openai.types.chat import ChatCompletion, ChatCompletionChunk, ChatCompletionMessage
+from openai.types.chat.chat_completion import Choice
 from openai.types.responses import Response
 from openai.types.responses.response_prompt_param import ResponsePromptParam
 from openai.types.responses.response_usage import InputTokensDetails, OutputTokensDetails
@@ -74,8 +75,11 @@ class OpenAIChatCompletionsModel(Model):
                 prompt=prompt,
             )
 
-            first_choice = response.choices[0]
-            message = first_choice.message
+            message: ChatCompletionMessage | None = None
+            first_choice: Choice | None = None
+            if response.choices and len(response.choices) > 0:
+                first_choice = response.choices[0]
+                message = first_choice.message
 
             if _debug.DONT_LOG_MODEL_DATA:
                 logger.debug("Received model response")
@@ -83,13 +87,11 @@ class OpenAIChatCompletionsModel(Model):
                 if message is not None:
                     logger.debug(
                         "LLM resp:\n%s\n",
-                        json.dumps(message.model_dump(), indent=2),
+                        json.dumps(message.model_dump(), indent=2, ensure_ascii=False),
                     )
                 else:
-                    logger.debug(
-                        "LLM resp had no message. finish_reason: %s",
-                        first_choice.finish_reason,
-                    )
+                    finish_reason = first_choice.finish_reason if first_choice else "-"
+                    logger.debug(f"LLM resp had no message. finish_reason: {finish_reason}")
 
             usage = (
                 Usage(
@@ -254,8 +256,8 @@ class OpenAIChatCompletionsModel(Model):
             logger.debug("Calling LLM")
         else:
             logger.debug(
-                f"{json.dumps(converted_messages, indent=2)}\n"
-                f"Tools:\n{json.dumps(converted_tools, indent=2)}\n"
+                f"{json.dumps(converted_messages, indent=2, ensure_ascii=False)}\n"
+                f"Tools:\n{json.dumps(converted_tools, indent=2, ensure_ascii=False)}\n"
                 f"Stream: {stream}\n"
                 f"Tool choice: {tool_choice}\n"
                 f"Response format: {response_format}\n"

agents/models/openai_responses.py

@@ -25,6 +25,7 @@ from ..exceptions import UserError
 from ..handoffs import Handoff
 from ..items import ItemHelpers, ModelResponse, TResponseInputItem
 from ..logger import logger
+from ..model_settings import MCPToolChoice
 from ..tool import (
     CodeInterpreterTool,
     ComputerTool,
@@ -96,7 +97,13 @@ class OpenAIResponsesModel(Model):
                 else:
                     logger.debug(
                         "LLM resp:\n"
-                        f"{json.dumps([x.model_dump() for x in response.output], indent=2)}\n"
+                        f"""{
+                            json.dumps(
+                                [x.model_dump() for x in response.output],
+                                indent=2,
+                                ensure_ascii=False,
+                            )
+                        }\n"""
                     )
 
                 usage = (
@@ -240,13 +247,17 @@ class OpenAIResponsesModel(Model):
         converted_tools = Converter.convert_tools(tools, handoffs)
         response_format = Converter.get_response_format(output_schema)
 
+        include: list[ResponseIncludable] = converted_tools.includes
+        if model_settings.response_include is not None:
+            include = list({*include, *model_settings.response_include})
+
         if _debug.DONT_LOG_MODEL_DATA:
             logger.debug("Calling LLM")
         else:
             logger.debug(
                 f"Calling LLM {self.model} with input:\n"
-                f"{json.dumps(list_input, indent=2)}\n"
-                f"Tools:\n{json.dumps(converted_tools.tools, indent=2)}\n"
+                f"{json.dumps(list_input, indent=2, ensure_ascii=False)}\n"
+                f"Tools:\n{json.dumps(converted_tools.tools, indent=2, ensure_ascii=False)}\n"
                 f"Stream: {stream}\n"
                 f"Tool choice: {tool_choice}\n"
                 f"Response format: {response_format}\n"
@@ -258,7 +269,7 @@ class OpenAIResponsesModel(Model):
             instructions=self._non_null_or_not_given(system_instructions),
             model=self.model,
             input=list_input,
-            include=converted_tools.includes,
+            include=include,
             tools=converted_tools.tools,
             prompt=self._non_null_or_not_given(prompt),
             temperature=self._non_null_or_not_given(model_settings.temperature),
@@ -293,10 +304,16 @@ class ConvertedTools:
 class Converter:
     @classmethod
     def convert_tool_choice(
-        cls, tool_choice: Literal["auto", "required", "none"] | str | None
+        cls, tool_choice: Literal["auto", "required", "none"] | str | MCPToolChoice | None
     ) -> response_create_params.ToolChoice | NotGiven:
         if tool_choice is None:
             return NOT_GIVEN
+        elif isinstance(tool_choice, MCPToolChoice):
+            return {
+                "server_label": tool_choice.server_label,
+                "type": "mcp",
+                "name": tool_choice.name,
+            }
         elif tool_choice == "required":
             return "required"
         elif tool_choice == "auto":
@@ -324,9 +341,9 @@ class Converter:
                 "type": "code_interpreter",
             }
         elif tool_choice == "mcp":
-            return {
-                "type": "mcp",
-            }
+            # Note that this is still here for backwards compatibility,
+            # but migrating to MCPToolChoice is recommended.
+            return {"type": "mcp"}  # type: ignore [typeddict-item]
         else:
             return {
                 "type": "function",

agents/realtime/README.md

@@ -0,0 +1,3 @@
+# Realtime
+
+Realtime agents are in beta: expect some breaking changes over the next few weeks as we find issues and fix them.

agents/realtime/__init__.py

@@ -0,0 +1,174 @@
+from .agent import RealtimeAgent, RealtimeAgentHooks, RealtimeRunHooks
+from .config import (
+    RealtimeAudioFormat,
+    RealtimeClientMessage,
+    RealtimeGuardrailsSettings,
+    RealtimeInputAudioTranscriptionConfig,
+    RealtimeModelName,
+    RealtimeModelTracingConfig,
+    RealtimeRunConfig,
+    RealtimeSessionModelSettings,
+    RealtimeTurnDetectionConfig,
+    RealtimeUserInput,
+    RealtimeUserInputMessage,
+    RealtimeUserInputText,
+)
+from .events import (
+    RealtimeAgentEndEvent,
+    RealtimeAgentStartEvent,
+    RealtimeAudio,
+    RealtimeAudioEnd,
+    RealtimeAudioInterrupted,
+    RealtimeError,
+    RealtimeEventInfo,
+    RealtimeGuardrailTripped,
+    RealtimeHandoffEvent,
+    RealtimeHistoryAdded,
+    RealtimeHistoryUpdated,
+    RealtimeRawModelEvent,
+    RealtimeSessionEvent,
+    RealtimeToolEnd,
+    RealtimeToolStart,
+)
+from .items import (
+    AssistantMessageItem,
+    AssistantText,
+    InputAudio,
+    InputText,
+    RealtimeItem,
+    RealtimeMessageItem,
+    RealtimeResponse,
+    RealtimeToolCallItem,
+    SystemMessageItem,
+    UserMessageItem,
+)
+from .model import (
+    RealtimeModel,
+    RealtimeModelConfig,
+    RealtimeModelListener,
+)
+from .model_events import (
+    RealtimeConnectionStatus,
+    RealtimeModelAudioDoneEvent,
+    RealtimeModelAudioEvent,
+    RealtimeModelAudioInterruptedEvent,
+    RealtimeModelConnectionStatusEvent,
+    RealtimeModelErrorEvent,
+    RealtimeModelEvent,
+    RealtimeModelExceptionEvent,
+    RealtimeModelInputAudioTranscriptionCompletedEvent,
+    RealtimeModelItemDeletedEvent,
+    RealtimeModelItemUpdatedEvent,
+    RealtimeModelOtherEvent,
+    RealtimeModelToolCallEvent,
+    RealtimeModelTranscriptDeltaEvent,
+    RealtimeModelTurnEndedEvent,
+    RealtimeModelTurnStartedEvent,
+)
+from .model_inputs import (
+    RealtimeModelInputTextContent,
+    RealtimeModelRawClientMessage,
+    RealtimeModelSendAudio,
+    RealtimeModelSendEvent,
+    RealtimeModelSendInterrupt,
+    RealtimeModelSendRawMessage,
+    RealtimeModelSendSessionUpdate,
+    RealtimeModelSendToolOutput,
+    RealtimeModelSendUserInput,
+    RealtimeModelUserInput,
+    RealtimeModelUserInputMessage,
+)
+from .openai_realtime import (
+    DEFAULT_MODEL_SETTINGS,
+    OpenAIRealtimeWebSocketModel,
+    get_api_key,
+)
+from .runner import RealtimeRunner
+from .session import RealtimeSession
+
+__all__ = [
+    # Agent
+    "RealtimeAgent",
+    "RealtimeAgentHooks",
+    "RealtimeRunHooks",
+    "RealtimeRunner",
+    # Config
+    "RealtimeAudioFormat",
+    "RealtimeClientMessage",
+    "RealtimeGuardrailsSettings",
+    "RealtimeInputAudioTranscriptionConfig",
+    "RealtimeModelName",
+    "RealtimeModelTracingConfig",
+    "RealtimeRunConfig",
+    "RealtimeSessionModelSettings",
+    "RealtimeTurnDetectionConfig",
+    "RealtimeUserInput",
+    "RealtimeUserInputMessage",
+    "RealtimeUserInputText",
+    # Events
+    "RealtimeAgentEndEvent",
+    "RealtimeAgentStartEvent",
+    "RealtimeAudio",
+    "RealtimeAudioEnd",
+    "RealtimeAudioInterrupted",
+    "RealtimeError",
+    "RealtimeEventInfo",
+    "RealtimeGuardrailTripped",
+    "RealtimeHandoffEvent",
+    "RealtimeHistoryAdded",
+    "RealtimeHistoryUpdated",
+    "RealtimeRawModelEvent",
+    "RealtimeSessionEvent",
+    "RealtimeToolEnd",
+    "RealtimeToolStart",
+    # Items
+    "AssistantMessageItem",
+    "AssistantText",
+    "InputAudio",
+    "InputText",
+    "RealtimeItem",
+    "RealtimeMessageItem",
+    "RealtimeResponse",
+    "RealtimeToolCallItem",
+    "SystemMessageItem",
+    "UserMessageItem",
+    # Model
+    "RealtimeModel",
+    "RealtimeModelConfig",
+    "RealtimeModelListener",
+    # Model Events
+    "RealtimeConnectionStatus",
+    "RealtimeModelAudioDoneEvent",
+    "RealtimeModelAudioEvent",
+    "RealtimeModelAudioInterruptedEvent",
+    "RealtimeModelConnectionStatusEvent",
+    "RealtimeModelErrorEvent",
+    "RealtimeModelEvent",
+    "RealtimeModelExceptionEvent",
+    "RealtimeModelInputAudioTranscriptionCompletedEvent",
+    "RealtimeModelItemDeletedEvent",
+    "RealtimeModelItemUpdatedEvent",
+    "RealtimeModelOtherEvent",
+    "RealtimeModelToolCallEvent",
+    "RealtimeModelTranscriptDeltaEvent",
+    "RealtimeModelTurnEndedEvent",
+    "RealtimeModelTurnStartedEvent",
+    # Model Inputs
+    "RealtimeModelInputTextContent",
+    "RealtimeModelRawClientMessage",
+    "RealtimeModelSendAudio",
+    "RealtimeModelSendEvent",
+    "RealtimeModelSendInterrupt",
+    "RealtimeModelSendRawMessage",
+    "RealtimeModelSendSessionUpdate",
+    "RealtimeModelSendToolOutput",
+    "RealtimeModelSendUserInput",
+    "RealtimeModelUserInput",
+    "RealtimeModelUserInputMessage",
+    # OpenAI Realtime
+    "DEFAULT_MODEL_SETTINGS",
+    "OpenAIRealtimeWebSocketModel",
+    "get_api_key",
+    # Session
+    "RealtimeSession",
+]

agents/realtime/agent.py

@@ -0,0 +1,80 @@
+from __future__ import annotations
+
+import dataclasses
+import inspect
+from collections.abc import Awaitable
+from dataclasses import dataclass
+from typing import Any, Callable, Generic, cast
+
+from ..agent import AgentBase
+from ..lifecycle import AgentHooksBase, RunHooksBase
+from ..logger import logger
+from ..run_context import RunContextWrapper, TContext
+from ..util._types import MaybeAwaitable
+
+RealtimeAgentHooks = AgentHooksBase[TContext, "RealtimeAgent[TContext]"]
+"""Agent hooks for `RealtimeAgent`s."""
+
+RealtimeRunHooks = RunHooksBase[TContext, "RealtimeAgent[TContext]"]
+"""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
+    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.
+    """
+
+    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.
+    """
+
+    hooks: RealtimeAgentHooks | None = None
+    """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)
+
+    async def get_system_prompt(self, run_context: RunContextWrapper[TContext]) -> str | None:
+        """Get the system prompt for the agent."""
+        if isinstance(self.instructions, str):
+            return self.instructions
+        elif callable(self.instructions):
+            if inspect.iscoroutinefunction(self.instructions):
+                return await cast(Awaitable[str], self.instructions(run_context, self))
+            else:
+                return cast(str, self.instructions(run_context, self))
+        elif self.instructions is not None:
+            logger.error(f"Instructions must be a string or a function, got {self.instructions}")
+
+        return None