Merge branch 'main' into feat/immediate-tool-call-item-streaming

Author: seratch

examples/realtime/app/agent.py

@@ -1,36 +1,93 @@
 from agents import function_tool
-from agents.realtime import RealtimeAgent
+from agents.extensions.handoff_prompt import RECOMMENDED_PROMPT_PREFIX
+from agents.realtime import RealtimeAgent, realtime_handoff
 
 """
 When running the UI example locally, you can edit this file to change the setup. THe server
 will use the agent returned from get_starting_agent() as the starting agent."""
 
+### TOOLS
+
+
+@function_tool(
+    name_override="faq_lookup_tool", description_override="Lookup frequently asked questions."
+)
+async def faq_lookup_tool(question: str) -> str:
+    if "bag" in question or "baggage" in question:
+        return (
+            "You are allowed to bring one bag on the plane. "
+            "It must be under 50 pounds and 22 inches x 14 inches x 9 inches."
+        )
+    elif "seats" in question or "plane" in question:
+        return (
+            "There are 120 seats on the plane. "
+            "There are 22 business class seats and 98 economy seats. "
+            "Exit rows are rows 4 and 16. "
+            "Rows 5-8 are Economy Plus, with extra legroom. "
+        )
+    elif "wifi" in question:
+        return "We have free wifi on the plane, join Airline-Wifi"
+    return "I'm sorry, I don't know the answer to that question."
+
+
+@function_tool
+async def update_seat(confirmation_number: str, new_seat: str) -> str:
+    """
+    Update the seat for a given confirmation number.
+
+    Args:
+        confirmation_number: The confirmation number for the flight.
+        new_seat: The new seat to update to.
+    """
+    return f"Updated seat to {new_seat} for confirmation number {confirmation_number}"
+
 
 @function_tool
 def get_weather(city: str) -> str:
     """Get the weather in a city."""
     return f"The weather in {city} is sunny."
 
 
-@function_tool
-def get_secret_number() -> int:
-    """Returns the secret number, if the user asks for it."""
-    return 71
-
+faq_agent = RealtimeAgent(
+    name="FAQ Agent",
+    handoff_description="A helpful agent that can answer questions about the airline.",
+    instructions=f"""{RECOMMENDED_PROMPT_PREFIX}
+    You are an FAQ agent. If you are speaking to a customer, you probably were transferred to from the triage agent.
+    Use the following routine to support the customer.
+    # Routine
+    1. Identify the last question asked by the customer.
+    2. Use the faq lookup tool to answer the question. Do not rely on your own knowledge.
+    3. If you cannot answer the question, transfer back to the triage agent.""",
+    tools=[faq_lookup_tool],
+)
 
-haiku_agent = RealtimeAgent(
-    name="Haiku Agent",
-    instructions="You are a haiku poet. You must respond ONLY in traditional haiku format (5-7-5 syllables). Every response should be a proper haiku about the topic. Do not break character.",
-    tools=[],
+seat_booking_agent = RealtimeAgent(
+    name="Seat Booking Agent",
+    handoff_description="A helpful agent that can update a seat on a flight.",
+    instructions=f"""{RECOMMENDED_PROMPT_PREFIX}
+    You are a seat booking agent. If you are speaking to a customer, you probably were transferred to from the triage agent.
+    Use the following routine to support the customer.
+    # Routine
+    1. Ask for their confirmation number.
+    2. Ask the customer what their desired seat number is.
+    3. Use the update seat tool to update the seat on the flight.
+    If the customer asks a question that is not related to the routine, transfer back to the triage agent. """,
+    tools=[update_seat],
 )
 
-assistant_agent = RealtimeAgent(
-    name="Assistant",
-    instructions="If the user wants poetry or haikus, you can hand them off to the haiku agent via the transfer_to_haiku_agent tool.",
-    tools=[get_weather, get_secret_number],
-    handoffs=[haiku_agent],
+triage_agent = RealtimeAgent(
+    name="Triage Agent",
+    handoff_description="A triage agent that can delegate a customer's request to the appropriate agent.",
+    instructions=(
+        f"{RECOMMENDED_PROMPT_PREFIX} "
+        "You are a helpful triaging agent. You can use your tools to delegate questions to other appropriate agents."
+    ),
+    handoffs=[faq_agent, realtime_handoff(seat_booking_agent)],
 )
 
+faq_agent.handoffs.append(triage_agent)
+seat_booking_agent.handoffs.append(triage_agent)
+
 
 def get_starting_agent() -> RealtimeAgent:
-    return assistant_agent
+    return triage_agent

pyproject.toml

@@ -1,13 +1,13 @@
 [project]
 name = "openai-agents"
-version = "0.2.5"
+version = "0.2.6"
 description = "OpenAI Agents SDK"
 readme = "README.md"
 requires-python = ">=3.9"
 license = "MIT"
 authors = [{ name = "OpenAI", email = "[email protected]" }]
 dependencies = [
-    "openai>=1.97.1,<2",
+    "openai>=1.99.6,<2",
     "pydantic>=2.10, <3",
     "griffe>=1.5.6, <2",
     "typing-extensions>=4.12.2, <5",

src/agents/agent.py

@@ -223,6 +223,119 @@ class Agent(AgentBase, Generic[TContext]):
     """Whether to reset the tool choice to the default value after a tool has been called. Defaults
     to True. This ensures that the agent doesn't enter an infinite loop of tool usage."""
 
+    def __post_init__(self):
+        from typing import get_origin
+
+        if not isinstance(self.name, str):
+            raise TypeError(f"Agent name must be a string, got {type(self.name).__name__}")
+
+        if self.handoff_description is not None and not isinstance(self.handoff_description, str):
+            raise TypeError(
+                f"Agent handoff_description must be a string or None, "
+                f"got {type(self.handoff_description).__name__}"
+            )
+
+        if not isinstance(self.tools, list):
+            raise TypeError(f"Agent tools must be a list, got {type(self.tools).__name__}")
+
+        if not isinstance(self.mcp_servers, list):
+            raise TypeError(
+                f"Agent mcp_servers must be a list, got {type(self.mcp_servers).__name__}"
+            )
+
+        if not isinstance(self.mcp_config, dict):
+            raise TypeError(
+                f"Agent mcp_config must be a dict, got {type(self.mcp_config).__name__}"
+            )
+
+        if (
+            self.instructions is not None
+            and not isinstance(self.instructions, str)
+            and not callable(self.instructions)
+        ):
+            raise TypeError(
+                f"Agent instructions must be a string, callable, or None, "
+                f"got {type(self.instructions).__name__}"
+            )
+
+        if (
+            self.prompt is not None
+            and not callable(self.prompt)
+            and not hasattr(self.prompt, "get")
+        ):
+            raise TypeError(
+                f"Agent prompt must be a Prompt, DynamicPromptFunction, or None, "
+                f"got {type(self.prompt).__name__}"
+            )
+
+        if not isinstance(self.handoffs, list):
+            raise TypeError(f"Agent handoffs must be a list, got {type(self.handoffs).__name__}")
+
+        if self.model is not None and not isinstance(self.model, str):
+            from .models.interface import Model
+
+            if not isinstance(self.model, Model):
+                raise TypeError(
+                    f"Agent model must be a string, Model, or None, got {type(self.model).__name__}"
+                )
+
+        if not isinstance(self.model_settings, ModelSettings):
+            raise TypeError(
+                f"Agent model_settings must be a ModelSettings instance, "
+                f"got {type(self.model_settings).__name__}"
+            )
+
+        if not isinstance(self.input_guardrails, list):
+            raise TypeError(
+                f"Agent input_guardrails must be a list, got {type(self.input_guardrails).__name__}"
+            )
+
+        if not isinstance(self.output_guardrails, list):
+            raise TypeError(
+                f"Agent output_guardrails must be a list, "
+                f"got {type(self.output_guardrails).__name__}"
+            )
+
+        if self.output_type is not None:
+            from .agent_output import AgentOutputSchemaBase
+
+            if not (
+                isinstance(self.output_type, (type, AgentOutputSchemaBase))
+                or get_origin(self.output_type) is not None
+            ):
+                raise TypeError(
+                    f"Agent output_type must be a type, AgentOutputSchemaBase, or None, "
+                    f"got {type(self.output_type).__name__}"
+                )
+
+        if self.hooks is not None:
+            from .lifecycle import AgentHooksBase
+
+            if not isinstance(self.hooks, AgentHooksBase):
+                raise TypeError(
+                    f"Agent hooks must be an AgentHooks instance or None, "
+                    f"got {type(self.hooks).__name__}"
+                )
+
+        if (
+            not (
+                isinstance(self.tool_use_behavior, str)
+                and self.tool_use_behavior in ["run_llm_again", "stop_on_first_tool"]
+            )
+            and not isinstance(self.tool_use_behavior, dict)
+            and not callable(self.tool_use_behavior)
+        ):
+            raise TypeError(
+                f"Agent tool_use_behavior must be 'run_llm_again', 'stop_on_first_tool', "
+                f"StopAtTools dict, or callable, got {type(self.tool_use_behavior).__name__}"
+            )
+
+        if not isinstance(self.reset_tool_choice, bool):
+            raise TypeError(
+                f"Agent reset_tool_choice must be a boolean, "
+                f"got {type(self.reset_tool_choice).__name__}"
+            )
+
     def clone(self, **kwargs: Any) -> Agent[TContext]:
         """Make a copy of the agent, with the given arguments changed.
         Notes:

src/agents/extensions/models/litellm_model.py

@@ -18,13 +18,17 @@
     ) from _e
 
 from openai import NOT_GIVEN, AsyncStream, NotGiven
-from openai.types.chat import ChatCompletionChunk, ChatCompletionMessageToolCall
+from openai.types.chat import (
+    ChatCompletionChunk,
+    ChatCompletionMessageFunctionToolCall,
+)
 from openai.types.chat.chat_completion_message import (
     Annotation,
     AnnotationURLCitation,
     ChatCompletionMessage,
 )
-from openai.types.chat.chat_completion_message_tool_call import Function
+from openai.types.chat.chat_completion_message_function_tool_call import Function
+from openai.types.chat.chat_completion_message_tool_call import ChatCompletionMessageToolCall
 from openai.types.responses import Response
 
 from ... import _debug
@@ -362,7 +366,7 @@ def convert_message_to_openai(
         if message.role != "assistant":
             raise ModelBehaviorError(f"Unsupported role: {message.role}")
 
-        tool_calls = (
+        tool_calls: list[ChatCompletionMessageToolCall] | None = (
             [LitellmConverter.convert_tool_call_to_openai(tool) for tool in message.tool_calls]
             if message.tool_calls
             else None
@@ -413,11 +417,12 @@ def convert_annotations_to_openai(
     @classmethod
     def convert_tool_call_to_openai(
         cls, tool_call: litellm.types.utils.ChatCompletionMessageToolCall
-    ) -> ChatCompletionMessageToolCall:
-        return ChatCompletionMessageToolCall(
+    ) -> ChatCompletionMessageFunctionToolCall:
+        return ChatCompletionMessageFunctionToolCall(
             id=tool_call.id,
             type="function",
             function=Function(
-                name=tool_call.function.name or "", arguments=tool_call.function.arguments
+                name=tool_call.function.name or "",
+                arguments=tool_call.function.arguments,
             ),
         )

src/agents/models/chatcmpl_converter.py

@@ -12,8 +12,8 @@
     ChatCompletionContentPartTextParam,
     ChatCompletionDeveloperMessageParam,
     ChatCompletionMessage,
+    ChatCompletionMessageFunctionToolCallParam,
     ChatCompletionMessageParam,
-    ChatCompletionMessageToolCallParam,
     ChatCompletionSystemMessageParam,
     ChatCompletionToolChoiceOptionParam,
     ChatCompletionToolMessageParam,
@@ -126,15 +126,18 @@ def message_to_output_items(cls, message: ChatCompletionMessage) -> list[TRespon
 
         if message.tool_calls:
             for tool_call in message.tool_calls:
-                items.append(
-                    ResponseFunctionToolCall(
-                        id=FAKE_RESPONSES_ID,
-                        call_id=tool_call.id,
-                        arguments=tool_call.function.arguments,
-                        name=tool_call.function.name,
-                        type="function_call",
+                if tool_call.type == "function":
+                    items.append(
+                        ResponseFunctionToolCall(
+                            id=FAKE_RESPONSES_ID,
+                            call_id=tool_call.id,
+                            arguments=tool_call.function.arguments,
+                            name=tool_call.function.name,
+                            type="function_call",
+                        )
                     )
-                )
+                elif tool_call.type == "custom":
+                    pass
 
         return items
 
@@ -420,7 +423,7 @@ def ensure_assistant_message() -> ChatCompletionAssistantMessageParam:
             elif file_search := cls.maybe_file_search_call(item):
                 asst = ensure_assistant_message()
                 tool_calls = list(asst.get("tool_calls", []))
-                new_tool_call = ChatCompletionMessageToolCallParam(
+                new_tool_call = ChatCompletionMessageFunctionToolCallParam(
                     id=file_search["id"],
                     type="function",
                     function={
@@ -440,7 +443,7 @@ def ensure_assistant_message() -> ChatCompletionAssistantMessageParam:
                 asst = ensure_assistant_message()
                 tool_calls = list(asst.get("tool_calls", []))
                 arguments = func_call["arguments"] if func_call["arguments"] else "{}"
-                new_tool_call = ChatCompletionMessageToolCallParam(
+                new_tool_call = ChatCompletionMessageFunctionToolCallParam(
                     id=func_call["call_id"],
                     type="function",
                     function={