openai-agents 0.2.11__py3-none-any.whl → 0.3.1__py3-none-any.whl

agents/_debug.py

@@ -1,17 +1,28 @@
 import os
 
 
-def _debug_flag_enabled(flag: str) -> bool:
+def _debug_flag_enabled(flag: str, default: bool = False) -> bool:
     flag_value = os.getenv(flag)
-    return flag_value is not None and (flag_value == "1" or flag_value.lower() == "true")
+    if flag_value is None:
+        return default
+    else:
+        return flag_value == "1" or flag_value.lower() == "true"
 
 
-DONT_LOG_MODEL_DATA = _debug_flag_enabled("OPENAI_AGENTS_DONT_LOG_MODEL_DATA")
+def _load_dont_log_model_data() -> bool:
+    return _debug_flag_enabled("OPENAI_AGENTS_DONT_LOG_MODEL_DATA", default=True)
+
+
+def _load_dont_log_tool_data() -> bool:
+    return _debug_flag_enabled("OPENAI_AGENTS_DONT_LOG_TOOL_DATA", default=True)
+
+
+DONT_LOG_MODEL_DATA = _load_dont_log_model_data()
 """By default we don't log LLM inputs/outputs, to prevent exposing sensitive information. Set this
 flag to enable logging them.
 """
 
-DONT_LOG_TOOL_DATA = _debug_flag_enabled("OPENAI_AGENTS_DONT_LOG_TOOL_DATA")
+DONT_LOG_TOOL_DATA = _load_dont_log_tool_data()
 """By default we don't log tool call inputs/outputs, to prevent exposing sensitive information. Set
 this flag to enable logging them.
 """

agents/_run_impl.py

@@ -330,43 +330,40 @@ class RunImpl:
             ItemHelpers.extract_last_text(message_items[-1].raw_item) if message_items else None
         )
 
-        # There are two possibilities that lead to a final output:
-        # 1. Structured output schema => always leads to a final output
-        # 2. Plain text output schema => only leads to a final output if there are no tool calls
-        if output_schema and not output_schema.is_plain_text() and potential_final_output_text:
-            final_output = output_schema.validate_json(potential_final_output_text)
-            return await cls.execute_final_output(
-                agent=agent,
-                original_input=original_input,
-                new_response=new_response,
-                pre_step_items=pre_step_items,
-                new_step_items=new_step_items,
-                final_output=final_output,
-                hooks=hooks,
-                context_wrapper=context_wrapper,
-            )
-        elif (
-            not output_schema or output_schema.is_plain_text()
-        ) and not processed_response.has_tools_or_approvals_to_run():
-            return await cls.execute_final_output(
-                agent=agent,
-                original_input=original_input,
-                new_response=new_response,
-                pre_step_items=pre_step_items,
-                new_step_items=new_step_items,
-                final_output=potential_final_output_text or "",
-                hooks=hooks,
-                context_wrapper=context_wrapper,
-            )
-        else:
-            # If there's no final output, we can just run again
-            return SingleStepResult(
-                original_input=original_input,
-                model_response=new_response,
-                pre_step_items=pre_step_items,
-                new_step_items=new_step_items,
-                next_step=NextStepRunAgain(),
-            )
+        # Generate final output only when there are no pending tool calls or approval requests.
+        if not processed_response.has_tools_or_approvals_to_run():
+            if output_schema and not output_schema.is_plain_text() and potential_final_output_text:
+                final_output = output_schema.validate_json(potential_final_output_text)
+                return await cls.execute_final_output(
+                    agent=agent,
+                    original_input=original_input,
+                    new_response=new_response,
+                    pre_step_items=pre_step_items,
+                    new_step_items=new_step_items,
+                    final_output=final_output,
+                    hooks=hooks,
+                    context_wrapper=context_wrapper,
+                )
+            elif not output_schema or output_schema.is_plain_text():
+                return await cls.execute_final_output(
+                    agent=agent,
+                    original_input=original_input,
+                    new_response=new_response,
+                    pre_step_items=pre_step_items,
+                    new_step_items=new_step_items,
+                    final_output=potential_final_output_text or "",
+                    hooks=hooks,
+                    context_wrapper=context_wrapper,
+                )
+
+        # If there's no final output, we can just run again
+        return SingleStepResult(
+            original_input=original_input,
+            model_response=new_response,
+            pre_step_items=pre_step_items,
+            new_step_items=new_step_items,
+            next_step=NextStepRunAgain(),
+        )
 
     @classmethod
     def maybe_reset_tool_choice(

agents/agent.py

@@ -30,9 +30,11 @@ from .util import _transforms
 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 @@ class Agent(AgentBase, Generic[TContext]):
         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 @@ class Agent(AgentBase, Generic[TContext]):
             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)

agents/extensions/handoff_filters.py

@@ -4,6 +4,7 @@ from ..handoffs import HandoffInputData
 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)

agents/extensions/memory/__init__.py

@@ -1,15 +1,42 @@
-
-"""Session memory backends living in the extensions namespace.
-
-This package contains optional, production-grade session implementations that
-introduce extra third-party dependencies (database drivers, ORMs, etc.). They
-conform to the :class:`agents.memory.session.Session` protocol so they can be
-used as a drop-in replacement for :class:`agents.memory.session.SQLiteSession`.
-"""
-from __future__ import annotations
-
-from .sqlalchemy_session import SQLAlchemySession  # noqa: F401
-
-__all__: list[str] = [
-    "SQLAlchemySession",
-]
+"""Session memory backends living in the extensions namespace.
+
+This package contains optional, production-grade session implementations that
+introduce extra third-party dependencies (database drivers, ORMs, etc.). They
+conform to the :class:`agents.memory.session.Session` protocol so they can be
+used as a drop-in replacement for :class:`agents.memory.session.SQLiteSession`.
+"""
+
+from __future__ import annotations
+
+from typing import Any
+
+__all__: list[str] = [
+    "EncryptedSession",
+    "SQLAlchemySession",
+]
+
+
+def __getattr__(name: str) -> Any:
+    if name == "EncryptedSession":
+        try:
+            from .encrypt_session import EncryptedSession  # noqa: F401
+
+            return EncryptedSession
+        except ModuleNotFoundError as e:
+            raise ImportError(
+                "EncryptedSession requires the 'cryptography' extra. "
+                "Install it with: pip install openai-agents[encrypt]"
+            ) from e
+
+    if name == "SQLAlchemySession":
+        try:
+            from .sqlalchemy_session import SQLAlchemySession  # noqa: F401
+
+            return SQLAlchemySession
+        except ModuleNotFoundError as e:
+            raise ImportError(
+                "SQLAlchemySession requires the 'sqlalchemy' extra. "
+                "Install it with: pip install openai-agents[sqlalchemy]"
+            ) from e
+
+    raise AttributeError(f"module {__name__} has no attribute {name}")

agents/extensions/memory/encrypt_session.py

@@ -0,0 +1,185 @@
+"""Encrypted Session wrapper for secure conversation storage.
+
+This module provides transparent encryption for session storage with automatic
+expiration of old data. When TTL expires, expired items are silently skipped.
+
+Usage::
+
+    from agents.extensions.memory import EncryptedSession, SQLAlchemySession
+
+    # Create underlying session (e.g. SQLAlchemySession)
+    underlying_session = SQLAlchemySession.from_url(
+        session_id="user-123",
+        url="postgresql+asyncpg://app:secret@db.example.com/agents",
+        create_tables=True,
+    )
+
+    # Wrap with encryption and TTL-based expiration
+    session = EncryptedSession(
+        session_id="user-123",
+        underlying_session=underlying_session,
+        encryption_key="your-encryption-key",
+        ttl=600,  # 10 minutes
+    )
+
+    await Runner.run(agent, "Hello", session=session)
+"""
+
+from __future__ import annotations
+
+import base64
+import json
+from typing import Any, cast
+
+from cryptography.fernet import Fernet, InvalidToken
+from cryptography.hazmat.primitives import hashes
+from cryptography.hazmat.primitives.kdf.hkdf import HKDF
+from typing_extensions import Literal, TypedDict, TypeGuard
+
+from ...items import TResponseInputItem
+from ...memory.session import SessionABC
+
+
+class EncryptedEnvelope(TypedDict):
+    """TypedDict for encrypted message envelopes stored in the underlying session."""
+
+    __enc__: Literal[1]
+    v: int
+    kid: str
+    payload: str
+
+
+def _ensure_fernet_key_bytes(master_key: str) -> bytes:
+    """
+    Accept either a Fernet key (urlsafe-b64, 32 bytes after decode) or a raw string.
+    Returns raw bytes suitable for HKDF input.
+    """
+    if not master_key:
+        raise ValueError("encryption_key not set; required for EncryptedSession.")
+    try:
+        key_bytes = base64.urlsafe_b64decode(master_key)
+        if len(key_bytes) == 32:
+            return key_bytes
+    except Exception:
+        pass
+    return master_key.encode("utf-8")
+
+
+def _derive_session_fernet_key(master_key_bytes: bytes, session_id: str) -> Fernet:
+    hkdf = HKDF(
+        algorithm=hashes.SHA256(),
+        length=32,
+        salt=session_id.encode("utf-8"),
+        info=b"agents.session-store.hkdf.v1",
+    )
+    derived = hkdf.derive(master_key_bytes)
+    return Fernet(base64.urlsafe_b64encode(derived))
+
+
+def _to_json_bytes(obj: Any) -> bytes:
+    return json.dumps(obj, ensure_ascii=False, separators=(",", ":"), default=str).encode("utf-8")
+
+
+def _from_json_bytes(data: bytes) -> Any:
+    return json.loads(data.decode("utf-8"))
+
+
+def _is_encrypted_envelope(item: object) -> TypeGuard[EncryptedEnvelope]:
+    """Type guard to check if an item is an encrypted envelope."""
+    return (
+        isinstance(item, dict)
+        and item.get("__enc__") == 1
+        and "payload" in item
+        and "kid" in item
+        and "v" in item
+    )
+
+
+class EncryptedSession(SessionABC):
+    """Encrypted wrapper for Session implementations with TTL-based expiration.
+
+    This class wraps any SessionABC implementation to provide transparent
+    encryption/decryption of stored items using Fernet encryption with
+    per-session key derivation and automatic expiration of old data.
+
+    When items expire (exceed TTL), they are silently skipped during retrieval.
+
+    Note: Expired tokens are rejected based on the system clock of the application server.
+    To avoid valid tokens being rejected due to clock drift, ensure all servers in
+    your environment are synchronized using NTP.
+    """
+
+    def __init__(
+        self,
+        session_id: str,
+        underlying_session: SessionABC,
+        encryption_key: str,
+        ttl: int = 600,
+    ):
+        """
+        Args:
+            session_id: ID for this session
+            underlying_session: The real session store (e.g. SQLiteSession, SQLAlchemySession)
+            encryption_key: Master key (Fernet key or raw secret)
+            ttl: Token time-to-live in seconds (default 10 min)
+        """
+        self.session_id = session_id
+        self.underlying_session = underlying_session
+        self.ttl = ttl
+
+        master = _ensure_fernet_key_bytes(encryption_key)
+        self.cipher = _derive_session_fernet_key(master, session_id)
+        self._kid = "hkdf-v1"
+        self._ver = 1
+
+    def __getattr__(self, name):
+        return getattr(self.underlying_session, name)
+
+    def _wrap(self, item: TResponseInputItem) -> EncryptedEnvelope:
+        if isinstance(item, dict):
+            payload = item
+        elif hasattr(item, "model_dump"):
+            payload = item.model_dump()
+        elif hasattr(item, "__dict__"):
+            payload = item.__dict__
+        else:
+            payload = dict(item)
+
+        token = self.cipher.encrypt(_to_json_bytes(payload)).decode("utf-8")
+        return {"__enc__": 1, "v": self._ver, "kid": self._kid, "payload": token}
+
+    def _unwrap(self, item: TResponseInputItem | EncryptedEnvelope) -> TResponseInputItem | None:
+        if not _is_encrypted_envelope(item):
+            return cast(TResponseInputItem, item)
+
+        try:
+            token = item["payload"].encode("utf-8")
+            plaintext = self.cipher.decrypt(token, ttl=self.ttl)
+            return cast(TResponseInputItem, _from_json_bytes(plaintext))
+        except (InvalidToken, KeyError):
+            return None
+
+    async def get_items(self, limit: int | None = None) -> list[TResponseInputItem]:
+        encrypted_items = await self.underlying_session.get_items(limit)
+        valid_items: list[TResponseInputItem] = []
+        for enc in encrypted_items:
+            item = self._unwrap(enc)
+            if item is not None:
+                valid_items.append(item)
+        return valid_items
+
+    async def add_items(self, items: list[TResponseInputItem]) -> None:
+        wrapped: list[EncryptedEnvelope] = [self._wrap(it) for it in items]
+        await self.underlying_session.add_items(cast(list[TResponseInputItem], wrapped))
+
+    async def pop_item(self) -> TResponseInputItem | None:
+        while True:
+            enc = await self.underlying_session.pop_item()
+            if not enc:
+                return None
+            item = self._unwrap(enc)
+            if item is not None:
+                return item
+
+    async def clear_session(self) -> None:
+        await self.underlying_session.clear_session()

agents/extensions/models/litellm_model.py

@@ -39,7 +39,7 @@ from ...items import ModelResponse, TResponseInputItem, TResponseStreamEvent
 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
@@ -48,14 +48,16 @@ from ...tracing import generation_span
 from ...tracing.span_data import GenerationSpanData
 from ...tracing.spans import Span
 from ...usage import Usage
+from ...util._json import _to_dump_compatible
 
 
 class InternalChatCompletionMessage(ChatCompletionMessage):
     """
-    An internal subclass to carry reasoning_content without modifying the original model.
-    """
+    An internal subclass to carry reasoning_content and thinking_blocks without modifying the original model.
+    """  # noqa: E501
 
     reasoning_content: str
+    thinking_blocks: list[dict[str, Any]] | None = None
 
 
 class LitellmModel(Model):
@@ -255,7 +257,15 @@ class LitellmModel(Model):
         stream: bool = False,
         prompt: Any | None = None,
     ) -> litellm.types.utils.ModelResponse | tuple[Response, AsyncStream[ChatCompletionChunk]]:
-        converted_messages = Converter.items_to_messages(input)
+        # Preserve reasoning messages for tool calls when reasoning is on
+        # This is needed for models like Claude 4 Sonnet/Opus which support interleaved thinking
+        preserve_thinking_blocks = (
+            model_settings.reasoning is not None and model_settings.reasoning.effort is not None
+        )
+
+        converted_messages = Converter.items_to_messages(
+            input, preserve_thinking_blocks=preserve_thinking_blocks
+        )
 
         if system_instructions:
             converted_messages.insert(
@@ -265,6 +275,8 @@ class LitellmModel(Model):
                     "role": "system",
                 },
             )
+        converted_messages = _to_dump_compatible(converted_messages)
+
         if tracing.include_data():
             span.span_data.input = converted_messages
 
@@ -283,13 +295,25 @@ class LitellmModel(Model):
         for handoff in handoffs:
             converted_tools.append(Converter.convert_handoff_tool(handoff))
 
+        converted_tools = _to_dump_compatible(converted_tools)
+
         if _debug.DONT_LOG_MODEL_DATA:
             logger.debug("Calling LLM")
         else:
+            messages_json = json.dumps(
+                converted_messages,
+                indent=2,
+                ensure_ascii=False,
+            )
+            tools_json = json.dumps(
+                converted_tools,
+                indent=2,
+                ensure_ascii=False,
+            )
             logger.debug(
                 f"Calling Litellm model: {self.model}\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"{messages_json}\n"
+                f"Tools:\n{tools_json}\n"
                 f"Stream: {stream}\n"
                 f"Tool choice: {tool_choice}\n"
                 f"Response format: {response_format}\n"
@@ -329,7 +353,7 @@ class LitellmModel(Model):
             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,
@@ -360,6 +384,13 @@ class LitellmModel(Model):
             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
@@ -369,9 +400,9 @@ class LitellmConverter:
         if message.role != "assistant":
             raise ModelBehaviorError(f"Unsupported role: {message.role}")
 
-        tool_calls: list[
-            ChatCompletionMessageFunctionToolCall | ChatCompletionMessageCustomToolCall
-        ] | None = (
+        tool_calls: (
+            list[ChatCompletionMessageFunctionToolCall | ChatCompletionMessageCustomToolCall] | None
+        ) = (
             [LitellmConverter.convert_tool_call_to_openai(tool) for tool in message.tool_calls]
             if message.tool_calls
             else None
@@ -386,6 +417,26 @@ class LitellmConverter:
         if hasattr(message, "reasoning_content") and message.reasoning_content:
             reasoning_content = message.reasoning_content
 
+        # Extract full thinking blocks including signatures (for Anthropic)
+        thinking_blocks: list[dict[str, Any]] | None = None
+        if hasattr(message, "thinking_blocks") and message.thinking_blocks:
+            # Convert thinking blocks to dict format for compatibility
+            thinking_blocks = []
+            for block in message.thinking_blocks:
+                if isinstance(block, dict):
+                    thinking_blocks.append(cast(dict[str, Any], block))
+                else:
+                    # Convert object to dict by accessing its attributes
+                    block_dict: dict[str, Any] = {}
+                    if hasattr(block, "__dict__"):
+                        block_dict = dict(block.__dict__.items())
+                    elif hasattr(block, "model_dump"):
+                        block_dict = block.model_dump()
+                    else:
+                        # Last resort: convert to string representation
+                        block_dict = {"thinking": str(block)}
+                    thinking_blocks.append(block_dict)
+
         return InternalChatCompletionMessage(
             content=message.content,
             refusal=refusal,
@@ -394,6 +445,7 @@ class LitellmConverter:
             audio=message.get("audio", None),  # litellm deletes audio if not present
             tool_calls=tool_calls,
             reasoning_content=reasoning_content,
+            thinking_blocks=thinking_blocks,
         )
 
     @classmethod

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 = []

agents/memory/__init__.py

@@ -1,10 +1,12 @@
 from .openai_conversations_session import OpenAIConversationsSession
 from .session import Session, SessionABC
 from .sqlite_session import SQLiteSession
+from .util import SessionInputCallback
 
 __all__ = [
     "Session",
     "SessionABC",
+    "SessionInputCallback",
     "SQLiteSession",
     "OpenAIConversationsSession",
 ]

agents/memory/openai_conversations_session.py

@@ -19,9 +19,6 @@ async def start_openai_conversations_session(openai_client: AsyncOpenAI | None =
     return response.id
 
 
-_EMPTY_SESSION_ID = ""
-
-
 class OpenAIConversationsSession(SessionABC):
     def __init__(
         self,