Merge branch 'main' into issue-1750-run-hooks

Author: seratch

examples/basic/tools.py

@@ -1,23 +1,23 @@
 import asyncio
+from typing import Annotated
 
-from pydantic import BaseModel
+from pydantic import BaseModel, Field
 
 from agents import Agent, Runner, function_tool
 
 
 class Weather(BaseModel):
-    city: str
-    temperature_range: str
-    conditions: str
+    city: str = Field(description="The city name")
+    temperature_range: str = Field(description="The temperature range in Celsius")
+    conditions: str = Field(description="The weather conditions")
 
 
 @function_tool
-def get_weather(city: str) -> Weather:
+def get_weather(city: Annotated[str, "The city to get the weather for"]) -> Weather:
     """Get the current weather information for a specified city."""
     print("[debug] get_weather called")
     return Weather(city=city, temperature_range="14-20C", conditions="Sunny with wind.")
 
-
 agent = Agent(
     name="Hello world",
     instructions="You are a helpful agent.",

pyproject.toml

@@ -1,6 +1,6 @@
 [project]
 name = "openai-agents"
-version = "0.3.0"
+version = "0.3.1"
 description = "OpenAI Agents SDK"
 readme = "README.md"
 requires-python = ">=3.9"

src/agents/agent.py

@@ -30,9 +30,11 @@
 from .util._types import MaybeAwaitable
 
 if TYPE_CHECKING:
-    from .lifecycle import AgentHooks
+    from .lifecycle import AgentHooks, RunHooks
     from .mcp import MCPServer
+    from .memory.session import Session
     from .result import RunResult
+    from .run import RunConfig
 
 
 @dataclass
@@ -384,6 +386,12 @@ def as_tool(
         custom_output_extractor: Callable[[RunResult], Awaitable[str]] | None = None,
         is_enabled: bool
         | Callable[[RunContextWrapper[Any], AgentBase[Any]], MaybeAwaitable[bool]] = True,
+        run_config: RunConfig | None = None,
+        max_turns: int | None = None,
+        hooks: RunHooks[TContext] | None = None,
+        previous_response_id: str | None = None,
+        conversation_id: str | None = None,
+        session: Session | None = None,
     ) -> Tool:
         """Transform this agent into a tool, callable by other agents.
 
@@ -410,12 +418,20 @@ def as_tool(
             is_enabled=is_enabled,
         )
         async def run_agent(context: RunContextWrapper, input: str) -> str:
-            from .run import Runner
+            from .run import DEFAULT_MAX_TURNS, Runner
+
+            resolved_max_turns = max_turns if max_turns is not None else DEFAULT_MAX_TURNS
 
             output = await Runner.run(
                 starting_agent=self,
                 input=input,
                 context=context.context,
+                run_config=run_config,
+                max_turns=resolved_max_turns,
+                hooks=hooks,
+                previous_response_id=previous_response_id,
+                conversation_id=conversation_id,
+                session=session,
             )
             if custom_output_extractor:
                 return await custom_output_extractor(output)

src/agents/extensions/handoff_filters.py

@@ -4,6 +4,7 @@
 from ..items import (
     HandoffCallItem,
     HandoffOutputItem,
+    ReasoningItem,
     RunItem,
     ToolCallItem,
     ToolCallOutputItem,
@@ -41,6 +42,7 @@ def _remove_tools_from_items(items: tuple[RunItem, ...]) -> tuple[RunItem, ...]:
             or isinstance(item, HandoffOutputItem)
             or isinstance(item, ToolCallItem)
             or isinstance(item, ToolCallOutputItem)
+            or isinstance(item, ReasoningItem)
         ):
             continue
         filtered_items.append(item)

src/agents/extensions/models/litellm_model.py

@@ -39,7 +39,7 @@
 from ...logger import logger
 from ...model_settings import ModelSettings
 from ...models.chatcmpl_converter import Converter
-from ...models.chatcmpl_helpers import HEADERS
+from ...models.chatcmpl_helpers import HEADERS, USER_AGENT_OVERRIDE
 from ...models.chatcmpl_stream_handler import ChatCmplStreamHandler
 from ...models.fake_id import FAKE_RESPONSES_ID
 from ...models.interface import Model, ModelTracing
@@ -353,7 +353,7 @@ async def _fetch_response(
             stream_options=stream_options,
             reasoning_effort=reasoning_effort,
             top_logprobs=model_settings.top_logprobs,
-            extra_headers={**HEADERS, **(model_settings.extra_headers or {})},
+            extra_headers=self._merge_headers(model_settings),
             api_key=self.api_key,
             base_url=self.base_url,
             **extra_kwargs,
@@ -384,6 +384,13 @@ def _remove_not_given(self, value: Any) -> Any:
             return None
         return value
 
+    def _merge_headers(self, model_settings: ModelSettings):
+        merged = {**HEADERS, **(model_settings.extra_headers or {})}
+        ua_ctx = USER_AGENT_OVERRIDE.get()
+        if ua_ctx is not None:
+            merged["User-Agent"] = ua_ctx
+        return merged
+
 
 class LitellmConverter:
     @classmethod

src/agents/function_schema.py

@@ -5,7 +5,7 @@
 import logging
 import re
 from dataclasses import dataclass
-from typing import Any, Callable, Literal, get_args, get_origin, get_type_hints
+from typing import Annotated, Any, Callable, Literal, get_args, get_origin, get_type_hints
 
 from griffe import Docstring, DocstringSectionKind
 from pydantic import BaseModel, Field, create_model
@@ -185,6 +185,31 @@ def generate_func_documentation(
     )
 
 
+def _strip_annotated(annotation: Any) -> tuple[Any, tuple[Any, ...]]:
+    """Returns the underlying annotation and any metadata from typing.Annotated."""
+
+    metadata: tuple[Any, ...] = ()
+    ann = annotation
+
+    while get_origin(ann) is Annotated:
+        args = get_args(ann)
+        if not args:
+            break
+        ann = args[0]
+        metadata = (*metadata, *args[1:])
+
+    return ann, metadata
+
+
+def _extract_description_from_metadata(metadata: tuple[Any, ...]) -> str | None:
+    """Extracts a human readable description from Annotated metadata if present."""
+
+    for item in metadata:
+        if isinstance(item, str):
+            return item
+    return None
+
+
 def function_schema(
     func: Callable[..., Any],
     docstring_style: DocstringStyle | None = None,
@@ -219,17 +244,34 @@ def function_schema(
     # 1. Grab docstring info
     if use_docstring_info:
         doc_info = generate_func_documentation(func, docstring_style)
-        param_descs = doc_info.param_descriptions or {}
+        param_descs = dict(doc_info.param_descriptions or {})
     else:
         doc_info = None
         param_descs = {}
 
+    type_hints_with_extras = get_type_hints(func, include_extras=True)
+    type_hints: dict[str, Any] = {}
+    annotated_param_descs: dict[str, str] = {}
+
+    for name, annotation in type_hints_with_extras.items():
+        if name == "return":
+            continue
+
+        stripped_ann, metadata = _strip_annotated(annotation)
+        type_hints[name] = stripped_ann
+
+        description = _extract_description_from_metadata(metadata)
+        if description is not None:
+            annotated_param_descs[name] = description
+
+    for name, description in annotated_param_descs.items():
+        param_descs.setdefault(name, description)
+
     # Ensure name_override takes precedence even if docstring info is disabled.
     func_name = name_override or (doc_info.name if doc_info else func.__name__)
 
     # 2. Inspect function signature and get type hints
     sig = inspect.signature(func)
-    type_hints = get_type_hints(func)
     params = list(sig.parameters.items())
     takes_context = False
     filtered_params = []

src/agents/models/chatcmpl_helpers.py

@@ -1,5 +1,7 @@
 from __future__ import annotations
 
+from contextvars import ContextVar
+
 from openai import AsyncOpenAI
 
 from ..model_settings import ModelSettings
@@ -8,6 +10,10 @@
 _USER_AGENT = f"Agents/Python {__version__}"
 HEADERS = {"User-Agent": _USER_AGENT}
 
+USER_AGENT_OVERRIDE: ContextVar[str | None] = ContextVar(
+    "openai_chatcompletions_user_agent_override", default=None
+)
+
 
 class ChatCmplHelpers:
     @classmethod

src/agents/models/openai_chatcompletions.py

@@ -25,7 +25,7 @@
 from ..usage import Usage
 from ..util._json import _to_dump_compatible
 from .chatcmpl_converter import Converter
-from .chatcmpl_helpers import HEADERS, ChatCmplHelpers
+from .chatcmpl_helpers import HEADERS, USER_AGENT_OVERRIDE, ChatCmplHelpers
 from .chatcmpl_stream_handler import ChatCmplStreamHandler
 from .fake_id import FAKE_RESPONSES_ID
 from .interface import Model, ModelTracing
@@ -306,7 +306,7 @@ async def _fetch_response(
             reasoning_effort=self._non_null_or_not_given(reasoning_effort),
             verbosity=self._non_null_or_not_given(model_settings.verbosity),
             top_logprobs=self._non_null_or_not_given(model_settings.top_logprobs),
-            extra_headers={**HEADERS, **(model_settings.extra_headers or {})},
+            extra_headers=self._merge_headers(model_settings),
             extra_query=model_settings.extra_query,
             extra_body=model_settings.extra_body,
             metadata=self._non_null_or_not_given(model_settings.metadata),
@@ -349,3 +349,10 @@ def _get_client(self) -> AsyncOpenAI:
         if self._client is None:
             self._client = AsyncOpenAI()
         return self._client
+
+    def _merge_headers(self, model_settings: ModelSettings):
+        merged = {**HEADERS, **(model_settings.extra_headers or {})}
+        ua_ctx = USER_AGENT_OVERRIDE.get()
+        if ua_ctx is not None:
+            merged["User-Agent"] = ua_ctx
+        return merged

src/agents/models/openai_responses.py

@@ -2,6 +2,7 @@
 
 import json
 from collections.abc import AsyncIterator
+from contextvars import ContextVar
 from dataclasses import dataclass
 from typing import TYPE_CHECKING, Any, Literal, cast, overload
 
@@ -49,6 +50,11 @@
 _USER_AGENT = f"Agents/Python {__version__}"
 _HEADERS = {"User-Agent": _USER_AGENT}
 
+# Override for the User-Agent header used by the Responses API.
+_USER_AGENT_OVERRIDE: ContextVar[str | None] = ContextVar(
+    "openai_responses_user_agent_override", default=None
+)
+
 
 class OpenAIResponsesModel(Model):
     """
@@ -312,7 +318,7 @@ async def _fetch_response(
             tool_choice=tool_choice,
             parallel_tool_calls=parallel_tool_calls,
             stream=stream,
-            extra_headers={**_HEADERS, **(model_settings.extra_headers or {})},
+            extra_headers=self._merge_headers(model_settings),
             extra_query=model_settings.extra_query,
             extra_body=model_settings.extra_body,
             text=response_format,
@@ -327,6 +333,13 @@ def _get_client(self) -> AsyncOpenAI:
             self._client = AsyncOpenAI()
         return self._client
 
+    def _merge_headers(self, model_settings: ModelSettings):
+        merged = {**_HEADERS, **(model_settings.extra_headers or {})}
+        ua_ctx = _USER_AGENT_OVERRIDE.get()
+        if ua_ctx is not None:
+            merged["User-Agent"] = ua_ctx
+        return merged
+
 
 @dataclass
 class ConvertedTools:

src/agents/util/_transforms.py

@@ -1,11 +1,21 @@
 import re
 
+from ..logger import logger
+
 
 def transform_string_function_style(name: str) -> str:
     # Replace spaces with underscores
     name = name.replace(" ", "_")
 
     # Replace non-alphanumeric characters with underscores
-    name = re.sub(r"[^a-zA-Z0-9]", "_", name)
+    transformed_name = re.sub(r"[^a-zA-Z0-9_]", "_", name)
+
+    if transformed_name != name:
+        final_name = transformed_name.lower()
+        logger.warning(
+            f"Tool name {name!r} contains invalid characters for function calling and has been "
+            f"transformed to {final_name!r}. Please use only letters, digits, and underscores "
+            "to avoid potential naming conflicts."
+        )
 
-    return name.lower()
+    return transformed_name.lower()