openai-agents 0.2.8__py3-none-any.whl → 0.6.8__py3-none-any.whl

agents/extensions/models/litellm_provider.py

@@ -1,6 +1,8 @@
+from ...models.default_models import get_default_model
 from ...models.interface import Model, ModelProvider
 from .litellm_model import LitellmModel
 
+# This is kept for backward compatiblity but using get_default_model() method is recommended.
 DEFAULT_MODEL: str = "gpt-4.1"
 
 
@@ -18,4 +20,4 @@ class LitellmProvider(ModelProvider):
     """
 
     def get_model(self, model_name: str | None) -> Model:
-        return LitellmModel(model_name or DEFAULT_MODEL)
+        return LitellmModel(model_name or get_default_model())

agents/function_schema.py

@@ -5,7 +5,7 @@ import inspect
 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 = []
@@ -291,7 +333,7 @@ def function_schema(
             # Default factory to empty list
             fields[name] = (
                 ann,
-                Field(default_factory=list, description=field_description),  # type: ignore
+                Field(default_factory=list, description=field_description),
             )
 
         elif param.kind == param.VAR_KEYWORD:
@@ -309,7 +351,7 @@ def function_schema(
 
             fields[name] = (
                 ann,
-                Field(default_factory=dict, description=field_description),  # type: ignore
+                Field(default_factory=dict, description=field_description),
             )
 
         else:

agents/guardrail.py

@@ -70,7 +70,7 @@ class OutputGuardrailResult:
 
 @dataclass
 class InputGuardrail(Generic[TContext]):
-    """Input guardrails are checks that run in parallel to the agent's execution.
+    """Input guardrails are checks that run either in parallel with the agent or before it starts.
     They can be used to do things like:
     - Check if input messages are off-topic
     - Take over control of the agent's execution if an unexpected input is detected
@@ -97,6 +97,11 @@ class InputGuardrail(Generic[TContext]):
     function's name.
     """
 
+    run_in_parallel: bool = True
+    """Whether the guardrail runs concurrently with the agent (True, default) or before
+    the agent starts (False).
+    """
+
     def get_name(self) -> str:
         if self.name:
             return self.name
@@ -209,6 +214,7 @@ def input_guardrail(
 def input_guardrail(
     *,
     name: str | None = None,
+    run_in_parallel: bool = True,
 ) -> Callable[
     [_InputGuardrailFuncSync[TContext_co] | _InputGuardrailFuncAsync[TContext_co]],
     InputGuardrail[TContext_co],
@@ -221,6 +227,7 @@ def input_guardrail(
     | None = None,
     *,
     name: str | None = None,
+    run_in_parallel: bool = True,
 ) -> (
     InputGuardrail[TContext_co]
     | Callable[
@@ -235,8 +242,14 @@ def input_guardrail(
         @input_guardrail
         def my_sync_guardrail(...): ...
 
-        @input_guardrail(name="guardrail_name")
+        @input_guardrail(name="guardrail_name", run_in_parallel=False)
         async def my_async_guardrail(...): ...
+
+    Args:
+        func: The guardrail function to wrap.
+        name: Optional name for the guardrail. If not provided, uses the function's name.
+        run_in_parallel: Whether to run the guardrail concurrently with the agent (True, default)
+            or before the agent starts (False).
     """
 
     def decorator(
@@ -246,6 +259,7 @@ def input_guardrail(
             guardrail_function=f,
             # If not set, guardrail name uses the function’s name by default.
             name=name if name else f.__name__,
+            run_in_parallel=run_in_parallel,
         )
 
     if func is not None:

agents/{handoffs.py → handoffs/__init__.py}

@@ -9,22 +9,29 @@ from typing import TYPE_CHECKING, Any, Callable, Generic, cast, overload
 from pydantic import TypeAdapter
 from typing_extensions import TypeAlias, TypeVar
 
-from .exceptions import ModelBehaviorError, UserError
-from .items import RunItem, TResponseInputItem
-from .run_context import RunContextWrapper, TContext
-from .strict_schema import ensure_strict_json_schema
-from .tracing.spans import SpanError
-from .util import _error_tracing, _json, _transforms
-from .util._types import MaybeAwaitable
+from ..exceptions import ModelBehaviorError, UserError
+from ..items import RunItem, TResponseInputItem
+from ..run_context import RunContextWrapper, TContext
+from ..strict_schema import ensure_strict_json_schema
+from ..tracing.spans import SpanError
+from ..util import _error_tracing, _json, _transforms
+from ..util._types import MaybeAwaitable
+from .history import (
+    default_handoff_history_mapper,
+    get_conversation_history_wrappers,
+    nest_handoff_history,
+    reset_conversation_history_wrappers,
+    set_conversation_history_wrappers,
+)
 
 if TYPE_CHECKING:
-    from .agent import Agent, AgentBase
+    from ..agent import Agent, AgentBase
 
 
 # The handoff input type is the type of data passed when the agent is called via a handoff.
 THandoffInput = TypeVar("THandoffInput", default=Any)
 
-# The agent type that the handoff returns
+# The agent type that the handoff returns.
 TAgent = TypeVar("TAgent", bound="AgentBase[Any]", default="Agent[Any]")
 
 OnHandoffWithInput = Callable[[RunContextWrapper[Any], THandoffInput], Any]
@@ -51,31 +58,44 @@ class HandoffInputData:
 
     run_context: RunContextWrapper[Any] | None = None
     """
-    The run context at the time the handoff was invoked.
-    Note that, since this property was added later on, it's optional for backwards compatibility.
+    The run context at the time the handoff was invoked. Note that, since this property was added
+    later on, it is optional for backwards compatibility.
+    """
+
+    input_items: tuple[RunItem, ...] | None = None
+    """
+    Items to include in the next agent's input. When set, these items are used instead of
+    new_items for building the input to the next agent. This allows filtering duplicates
+    from agent input while preserving all items in new_items for session history.
     """
 
     def clone(self, **kwargs: Any) -> HandoffInputData:
         """
         Make a copy of the handoff input data, with the given arguments changed. For example, you
         could do:
+
         ```
         new_handoff_input_data = handoff_input_data.clone(new_items=())
         ```
         """
+
         return dataclasses_replace(self, **kwargs)
 
 
 HandoffInputFilter: TypeAlias = Callable[[HandoffInputData], MaybeAwaitable[HandoffInputData]]
 """A function that filters the input data passed to the next agent."""
 
+HandoffHistoryMapper: TypeAlias = Callable[[list[TResponseInputItem]], list[TResponseInputItem]]
+"""A function that maps the previous transcript to the nested summary payload."""
+
 
 @dataclass
 class Handoff(Generic[TContext, TAgent]):
     """A handoff is when an agent delegates a task to another agent.
+
     For example, in a customer support scenario you might have a "triage agent" that determines
-    which agent should handle the user's request, and sub-agents that specialize in different
-    areas like billing, account management, etc.
+    which agent should handle the user's request, and sub-agents that specialize in different areas
+    like billing, account management, etc.
     """
 
     tool_name: str
@@ -85,46 +105,48 @@ class Handoff(Generic[TContext, TAgent]):
     """The description of the tool that represents the handoff."""
 
     input_json_schema: dict[str, Any]
-    """The JSON schema for the handoff input. Can be empty if the handoff does not take an input.
-    """
+    """The JSON schema for the handoff input. Can be empty if the handoff does not take an input."""
 
     on_invoke_handoff: Callable[[RunContextWrapper[Any], str], Awaitable[TAgent]]
-    """The function that invokes the handoff. The parameters passed are:
-    1. The handoff run context
-    2. The arguments from the LLM, as a JSON string. Empty string if input_json_schema is empty.
+    """The function that invokes the handoff.
 
-    Must return an agent.
+    The parameters passed are: (1) the handoff run context, (2) the arguments from the LLM as a
+    JSON string (or an empty string if ``input_json_schema`` is empty). Must return an agent.
     """
 
     agent_name: str
     """The name of the agent that is being handed off to."""
 
     input_filter: HandoffInputFilter | None = None
-    """A function that filters the inputs that are passed to the next agent. By default, the new
-    agent sees the entire conversation history. In some cases, you may want to filter inputs e.g.
-    to remove older inputs, or remove tools from existing inputs.
-
-    The function will receive the entire conversation history so far, including the input item
-    that triggered the handoff and a tool call output item representing the handoff tool's output.
-
-    You are free to modify the input history or new items as you see fit. The next agent that
-    runs will receive `handoff_input_data.all_items`.
-
+    """A function that filters the inputs that are passed to the next agent.
+
+    By default, the new agent sees the entire conversation history. In some cases, you may want to
+    filter inputs (for example, to remove older inputs or remove tools from existing inputs). The
+    function receives the entire conversation history so far, including the input item that
+    triggered the handoff and a tool call output item representing the handoff tool's output. You
+    are free to modify the input history or new items as you see fit. The next agent receives the
+    input history plus ``input_items`` when provided, otherwise it receives ``new_items``. Use
+    ``input_items`` to filter model input while keeping ``new_items`` intact for session history.
     IMPORTANT: in streaming mode, we will not stream anything as a result of this function. The
     items generated before will already have been streamed.
     """
 
+    nest_handoff_history: bool | None = None
+    """Override the run-level ``nest_handoff_history`` behavior for this handoff only."""
+
     strict_json_schema: bool = True
-    """Whether the input JSON schema is in strict mode. We **strongly** recommend setting this to
-    True, as it increases the likelihood of correct JSON input.
-    """
+    """Whether the input JSON schema is in strict mode. We strongly recommend setting this to True
+    because it increases the likelihood of correct JSON input."""
 
-    is_enabled: bool | Callable[
-        [RunContextWrapper[Any], AgentBase[Any]], MaybeAwaitable[bool]
-    ] = True
-    """Whether the handoff is enabled. Either a bool or a Callable that takes the run context and
-    agent and returns whether the handoff is enabled. You can use this to dynamically enable/disable
-    a handoff based on your context/state."""
+    is_enabled: bool | Callable[[RunContextWrapper[Any], AgentBase[Any]], MaybeAwaitable[bool]] = (
+        True
+    )
+    """Whether the handoff is enabled.
+
+    Either a bool or a callable that takes the run context and agent and returns whether the
+    handoff is enabled. You can use this to dynamically enable or disable a handoff based on your
+    context or state.
+    """
 
     def get_transfer_message(self, agent: AgentBase[Any]) -> str:
         return json.dumps({"assistant": agent.name})
@@ -148,6 +170,7 @@ def handoff(
     tool_name_override: str | None = None,
     tool_description_override: str | None = None,
     input_filter: Callable[[HandoffInputData], HandoffInputData] | None = None,
+    nest_handoff_history: bool | None = None,
     is_enabled: bool | Callable[[RunContextWrapper[Any], Agent[Any]], MaybeAwaitable[bool]] = True,
 ) -> Handoff[TContext, Agent[TContext]]: ...
 
@@ -161,6 +184,7 @@ def handoff(
     tool_description_override: str | None = None,
     tool_name_override: str | None = None,
     input_filter: Callable[[HandoffInputData], HandoffInputData] | None = None,
+    nest_handoff_history: bool | None = None,
     is_enabled: bool | Callable[[RunContextWrapper[Any], Agent[Any]], MaybeAwaitable[bool]] = True,
 ) -> Handoff[TContext, Agent[TContext]]: ...
 
@@ -173,6 +197,7 @@ def handoff(
     tool_description_override: str | None = None,
     tool_name_override: str | None = None,
     input_filter: Callable[[HandoffInputData], HandoffInputData] | None = None,
+    nest_handoff_history: bool | None = None,
     is_enabled: bool | Callable[[RunContextWrapper[Any], Agent[Any]], MaybeAwaitable[bool]] = True,
 ) -> Handoff[TContext, Agent[TContext]]: ...
 
@@ -184,24 +209,28 @@ def handoff(
     on_handoff: OnHandoffWithInput[THandoffInput] | OnHandoffWithoutInput | None = None,
     input_type: type[THandoffInput] | None = None,
     input_filter: Callable[[HandoffInputData], HandoffInputData] | None = None,
+    nest_handoff_history: bool | None = None,
     is_enabled: bool
     | Callable[[RunContextWrapper[Any], Agent[TContext]], MaybeAwaitable[bool]] = True,
 ) -> Handoff[TContext, Agent[TContext]]:
     """Create a handoff from an agent.
 
     Args:
-        agent: The agent to handoff to, or a function that returns an agent.
+        agent: The agent to handoff to.
         tool_name_override: Optional override for the name of the tool that represents the handoff.
         tool_description_override: Optional override for the description of the tool that
             represents the handoff.
         on_handoff: A function that runs when the handoff is invoked.
-        input_type: the type of the input to the handoff. If provided, the input will be validated
+        input_type: The type of the input to the handoff. If provided, the input will be validated
             against this type. Only relevant if you pass a function that takes an input.
-        input_filter: a function that filters the inputs that are passed to the next agent.
+        input_filter: A function that filters the inputs that are passed to the next agent.
+        nest_handoff_history: Optional override for the RunConfig-level ``nest_handoff_history``
+            flag. If ``None`` we fall back to the run's configuration.
         is_enabled: Whether the handoff is enabled. Can be a bool or a callable that takes the run
             context and agent and returns whether the handoff is enabled. Disabled handoffs are
             hidden from the LLM at runtime.
     """
+
     assert (on_handoff and input_type) or not (on_handoff and input_type), (
         "You must provide either both on_handoff and input_type, or neither"
     )
@@ -257,21 +286,19 @@ def handoff(
     tool_name = tool_name_override or Handoff.default_tool_name(agent)
     tool_description = tool_description_override or Handoff.default_tool_description(agent)
 
-    # Always ensure the input JSON schema is in strict mode
-    # If there is a need, we can make this configurable in the future
+    # Always ensure the input JSON schema is in strict mode. If needed, we can make this
+    # configurable in the future.
     input_json_schema = ensure_strict_json_schema(input_json_schema)
 
     async def _is_enabled(ctx: RunContextWrapper[Any], agent_base: AgentBase[Any]) -> bool:
-        from .agent import Agent
+        from ..agent import Agent
 
         assert callable(is_enabled), "is_enabled must be callable here"
         assert isinstance(agent_base, Agent), "Can't handoff to a non-Agent"
         result = is_enabled(ctx, agent_base)
-
         if inspect.isawaitable(result):
             return await result
-
-        return result
+        return bool(result)
 
     return Handoff(
         tool_name=tool_name,
@@ -279,6 +306,21 @@ def handoff(
         input_json_schema=input_json_schema,
         on_invoke_handoff=_invoke_handoff,
         input_filter=input_filter,
+        nest_handoff_history=nest_handoff_history,
         agent_name=agent.name,
         is_enabled=_is_enabled if callable(is_enabled) else is_enabled,
     )
+
+
+__all__ = [
+    "Handoff",
+    "HandoffHistoryMapper",
+    "HandoffInputData",
+    "HandoffInputFilter",
+    "default_handoff_history_mapper",
+    "get_conversation_history_wrappers",
+    "handoff",
+    "nest_handoff_history",
+    "reset_conversation_history_wrappers",
+    "set_conversation_history_wrappers",
+]