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

agents/__init__.py

@@ -46,7 +46,7 @@ from .items import (
     TResponseInputItem,
 )
 from .lifecycle import AgentHooks, RunHooks
-from .memory import Session, SQLiteSession
+from .memory import OpenAIConversationsSession, Session, SessionABC, SQLiteSession
 from .model_settings import ModelSettings
 from .models.interface import Model, ModelProvider, ModelTracing
 from .models.multi_provider import MultiProvider
@@ -221,7 +221,9 @@ __all__ = [
     "RunHooks",
     "AgentHooks",
     "Session",
+    "SessionABC",
     "SQLiteSession",
+    "OpenAIConversationsSession",
     "RunContextWrapper",
     "TContext",
     "RunErrorDetails",

agents/_run_impl.py

@@ -509,13 +509,29 @@ class RunImpl:
             # Regular function tool call
             else:
                 if output.name not in function_map:
-                    _error_tracing.attach_error_to_current_span(
-                        SpanError(
-                            message="Tool not found",
-                            data={"tool_name": output.name},
+                    if output_schema is not None and output.name == "json_tool_call":
+                        # LiteLLM could generate non-existent tool calls for structured outputs
+                        items.append(ToolCallItem(raw_item=output, agent=agent))
+                        functions.append(
+                            ToolRunFunction(
+                                tool_call=output,
+                                # this tool does not exist in function_map, so generate ad-hoc one,
+                                # which just parses the input if it's a string, and returns the
+                                # value otherwise
+                                function_tool=_build_litellm_json_tool_call(output),
+                            )
                         )
-                    )
-                    raise ModelBehaviorError(f"Tool {output.name} not found in agent {agent.name}")
+                        continue
+                    else:
+                        _error_tracing.attach_error_to_current_span(
+                            SpanError(
+                                message="Tool not found",
+                                data={"tool_name": output.name},
+                            )
+                        )
+                        error = f"Tool {output.name} not found in agent {agent.name}"
+                        raise ModelBehaviorError(error)
+
                 items.append(ToolCallItem(raw_item=output, agent=agent))
                 functions.append(
                     ToolRunFunction(
@@ -961,7 +977,10 @@ class RunImpl:
         context_wrapper: RunContextWrapper[TContext],
         config: RunConfig,
     ) -> ToolsToFinalOutputResult:
-        """Returns (i, final_output)."""
+        """Determine if tool results should produce a final output.
+        Returns:
+            ToolsToFinalOutputResult: Indicates whether final output is ready, and the output value.
+        """
         if not tool_results:
             return _NOT_FINAL_OUTPUT
 
@@ -1190,3 +1209,21 @@ class LocalShellAction:
                 # "id": "out" + call.tool_call.id,  # TODO remove this, it should be optional
             },
         )
+
+
+def _build_litellm_json_tool_call(output: ResponseFunctionToolCall) -> FunctionTool:
+    async def on_invoke_tool(_ctx: ToolContext[Any], value: Any) -> Any:
+        if isinstance(value, str):
+            import json
+
+            return json.loads(value)
+        return value
+
+    return FunctionTool(
+        name=output.name,
+        description=output.name,
+        params_json_schema={},
+        on_invoke_tool=on_invoke_tool,
+        strict_json_schema=True,
+        is_enabled=True,
+    )

agents/agent.py

@@ -17,6 +17,11 @@ from .items import ItemHelpers
 from .logger import logger
 from .mcp import MCPUtil
 from .model_settings import ModelSettings
+from .models.default_models import (
+    get_default_model_settings,
+    gpt_5_reasoning_settings_required,
+    is_gpt_5_default,
+)
 from .models.interface import Model
 from .prompts import DynamicPromptFunction, Prompt, PromptUtil
 from .run_context import RunContextWrapper, TContext
@@ -168,10 +173,10 @@ class Agent(AgentBase, Generic[TContext]):
     """The model implementation to use when invoking the LLM.
 
     By default, if not set, the agent will use the default model configured in
-    `openai_provider.DEFAULT_MODEL` (currently "gpt-4o").
+    `agents.models.get_default_model()` (currently "gpt-4.1").
     """
 
-    model_settings: ModelSettings = field(default_factory=ModelSettings)
+    model_settings: ModelSettings = field(default_factory=get_default_model_settings)
     """Configures model-specific tuning parameters (e.g. temperature, top_p).
     """
 
@@ -205,8 +210,9 @@ class Agent(AgentBase, Generic[TContext]):
     This lets you configure how tool use is handled.
     - "run_llm_again": The default behavior. Tools are run, and then the LLM receives the results
         and gets to respond.
-    - "stop_on_first_tool": The output of the first tool call is used as the final output. This
-        means that the LLM does not process the result of the tool call.
+    - "stop_on_first_tool": The output from the first tool call is treated as the final result.
+        In other words, it isn’t sent back to the LLM for further processing but is used directly
+        as the final output.
     - A StopAtTools object: The agent will stop running if any of the tools listed in
         `stop_at_tool_names` is called.
         The final output will be the output of the first matching tool call.
@@ -285,6 +291,26 @@ class Agent(AgentBase, Generic[TContext]):
                 f"got {type(self.model_settings).__name__}"
             )
 
+        if (
+            # The user sets a non-default model
+            self.model is not None
+            and (
+                # The default model is gpt-5
+                is_gpt_5_default() is True
+                # However, the specified model is not a gpt-5 model
+                and (
+                    isinstance(self.model, str) is False
+                    or gpt_5_reasoning_settings_required(self.model) is False  # type: ignore
+                )
+                # The model settings are not customized for the specified model
+                and self.model_settings == get_default_model_settings()
+            )
+        ):
+            # In this scenario, we should use a generic model settings
+            # because non-gpt-5 models are not compatible with the default gpt-5 model settings.
+            # This is a best-effort attempt to make the agent work with non-gpt-5 models.
+            self.model_settings = ModelSettings()
+
         if not isinstance(self.input_guardrails, list):
             raise TypeError(
                 f"Agent input_guardrails must be a list, got {type(self.input_guardrails).__name__}"
@@ -356,6 +382,8 @@ class Agent(AgentBase, Generic[TContext]):
         tool_name: str | None,
         tool_description: str | None,
         custom_output_extractor: Callable[[RunResult], Awaitable[str]] | None = None,
+        is_enabled: bool
+        | Callable[[RunContextWrapper[Any], AgentBase[Any]], MaybeAwaitable[bool]] = True,
     ) -> Tool:
         """Transform this agent into a tool, callable by other agents.
 
@@ -371,11 +399,15 @@ class Agent(AgentBase, Generic[TContext]):
                 when to use it.
             custom_output_extractor: A function that extracts the output from the agent. If not
                 provided, the last message from the agent will be used.
+            is_enabled: Whether the tool is enabled. Can be a bool or a callable that takes the run
+                context and agent and returns whether the tool is enabled. Disabled tools are hidden
+                from the LLM at runtime.
         """
 
         @function_tool(
             name_override=tool_name or _transforms.transform_string_function_style(self.name),
             description_override=tool_description or "",
+            is_enabled=is_enabled,
         )
         async def run_agent(context: RunContextWrapper, input: str) -> str:
             from .run import Runner

agents/extensions/memory/__init__.py

@@ -0,0 +1,15 @@
+
+"""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",
+]

agents/extensions/memory/sqlalchemy_session.py

@@ -0,0 +1,312 @@
+"""SQLAlchemy-powered Session backend.
+
+Usage::
+
+    from agents.extensions.memory import SQLAlchemySession
+
+    # Create from SQLAlchemy URL (uses asyncpg driver under the hood for Postgres)
+    session = SQLAlchemySession.from_url(
+        session_id="user-123",
+        url="postgresql+asyncpg://app:secret@db.example.com/agents",
+        create_tables=True, # If you want to auto-create tables, set to True.
+    )
+
+    # Or pass an existing AsyncEngine that your application already manages
+    session = SQLAlchemySession(
+        session_id="user-123",
+        engine=my_async_engine,
+        create_tables=True, # If you want to auto-create tables, set to True.
+    )
+
+    await Runner.run(agent, "Hello", session=session)
+"""
+
+from __future__ import annotations
+
+import asyncio
+import json
+from typing import Any
+
+from sqlalchemy import (
+    TIMESTAMP,
+    Column,
+    ForeignKey,
+    Index,
+    Integer,
+    MetaData,
+    String,
+    Table,
+    Text,
+    delete,
+    insert,
+    select,
+    text as sql_text,
+    update,
+)
+from sqlalchemy.ext.asyncio import AsyncEngine, async_sessionmaker, create_async_engine
+
+from ...items import TResponseInputItem
+from ...memory.session import SessionABC
+
+
+class SQLAlchemySession(SessionABC):
+    """SQLAlchemy implementation of :pyclass:`agents.memory.session.Session`."""
+
+    _metadata: MetaData
+    _sessions: Table
+    _messages: Table
+
+    def __init__(
+        self,
+        session_id: str,
+        *,
+        engine: AsyncEngine,
+        create_tables: bool = False,
+        sessions_table: str = "agent_sessions",
+        messages_table: str = "agent_messages",
+    ):
+        """Initializes a new SQLAlchemySession.
+
+        Args:
+            session_id (str): Unique identifier for the conversation.
+            engine (AsyncEngine): A pre-configured SQLAlchemy async engine. The engine
+                must be created with an async driver (e.g., 'postgresql+asyncpg://',
+                'mysql+aiomysql://', or 'sqlite+aiosqlite://').
+            create_tables (bool, optional): Whether to automatically create the required
+                tables and indexes. Defaults to False for production use. Set to True for
+                development and testing when migrations aren't used.
+            sessions_table (str, optional): Override the default table name for sessions if needed.
+            messages_table (str, optional): Override the default table name for messages if needed.
+        """
+        self.session_id = session_id
+        self._engine = engine
+        self._lock = asyncio.Lock()
+
+        self._metadata = MetaData()
+        self._sessions = Table(
+            sessions_table,
+            self._metadata,
+            Column("session_id", String, primary_key=True),
+            Column(
+                "created_at",
+                TIMESTAMP(timezone=False),
+                server_default=sql_text("CURRENT_TIMESTAMP"),
+                nullable=False,
+            ),
+            Column(
+                "updated_at",
+                TIMESTAMP(timezone=False),
+                server_default=sql_text("CURRENT_TIMESTAMP"),
+                onupdate=sql_text("CURRENT_TIMESTAMP"),
+                nullable=False,
+            ),
+        )
+
+        self._messages = Table(
+            messages_table,
+            self._metadata,
+            Column("id", Integer, primary_key=True, autoincrement=True),
+            Column(
+                "session_id",
+                String,
+                ForeignKey(f"{sessions_table}.session_id", ondelete="CASCADE"),
+                nullable=False,
+            ),
+            Column("message_data", Text, nullable=False),
+            Column(
+                "created_at",
+                TIMESTAMP(timezone=False),
+                server_default=sql_text("CURRENT_TIMESTAMP"),
+                nullable=False,
+            ),
+            Index(
+                f"idx_{messages_table}_session_time",
+                "session_id",
+                "created_at",
+            ),
+            sqlite_autoincrement=True,
+        )
+
+        # Async session factory
+        self._session_factory = async_sessionmaker(self._engine, expire_on_commit=False)
+
+        self._create_tables = create_tables
+
+    # ---------------------------------------------------------------------
+    # Convenience constructors
+    # ---------------------------------------------------------------------
+    @classmethod
+    def from_url(
+        cls,
+        session_id: str,
+        *,
+        url: str,
+        engine_kwargs: dict[str, Any] | None = None,
+        **kwargs: Any,
+    ) -> SQLAlchemySession:
+        """Create a session from a database URL string.
+
+        Args:
+            session_id (str): Conversation ID.
+            url (str): Any SQLAlchemy async URL, e.g. "postgresql+asyncpg://user:pass@host/db".
+            engine_kwargs (dict[str, Any] | None): Additional keyword arguments forwarded to
+                sqlalchemy.ext.asyncio.create_async_engine.
+            **kwargs: Additional keyword arguments forwarded to the main constructor
+                (e.g., create_tables, custom table names, etc.).
+
+        Returns:
+            SQLAlchemySession: An instance of SQLAlchemySession connected to the specified database.
+        """
+        engine_kwargs = engine_kwargs or {}
+        engine = create_async_engine(url, **engine_kwargs)
+        return cls(session_id, engine=engine, **kwargs)
+
+    async def _serialize_item(self, item: TResponseInputItem) -> str:
+        """Serialize an item to JSON string. Can be overridden by subclasses."""
+        return json.dumps(item, separators=(",", ":"))
+
+    async def _deserialize_item(self, item: str) -> TResponseInputItem:
+        """Deserialize a JSON string to an item. Can be overridden by subclasses."""
+        return json.loads(item)  # type: ignore[no-any-return]
+
+    # ------------------------------------------------------------------
+    # Session protocol implementation
+    # ------------------------------------------------------------------
+    async def _ensure_tables(self) -> None:
+        """Ensure tables are created before any database operations."""
+        if self._create_tables:
+            async with self._engine.begin() as conn:
+                await conn.run_sync(self._metadata.create_all)
+            self._create_tables = False  # Only create once
+
+    async def get_items(self, limit: int | None = None) -> list[TResponseInputItem]:
+        """Retrieve the conversation history for this session.
+
+        Args:
+            limit: Maximum number of items to retrieve. If None, retrieves all items.
+                   When specified, returns the latest N items in chronological order.
+
+        Returns:
+            List of input items representing the conversation history
+        """
+        await self._ensure_tables()
+        async with self._session_factory() as sess:
+            if limit is None:
+                stmt = (
+                    select(self._messages.c.message_data)
+                    .where(self._messages.c.session_id == self.session_id)
+                    .order_by(self._messages.c.created_at.asc())
+                )
+            else:
+                stmt = (
+                    select(self._messages.c.message_data)
+                    .where(self._messages.c.session_id == self.session_id)
+                    # Use DESC + LIMIT to get the latest N
+                    # then reverse later for chronological order.
+                    .order_by(self._messages.c.created_at.desc())
+                    .limit(limit)
+                )
+
+            result = await sess.execute(stmt)
+            rows: list[str] = [row[0] for row in result.all()]
+
+            if limit is not None:
+                rows.reverse()
+
+            items: list[TResponseInputItem] = []
+            for raw in rows:
+                try:
+                    items.append(await self._deserialize_item(raw))
+                except json.JSONDecodeError:
+                    # Skip corrupted rows
+                    continue
+            return items
+
+    async def add_items(self, items: list[TResponseInputItem]) -> None:
+        """Add new items to the conversation history.
+
+        Args:
+            items: List of input items to add to the history
+        """
+        if not items:
+            return
+
+        await self._ensure_tables()
+        payload = [
+            {
+                "session_id": self.session_id,
+                "message_data": await self._serialize_item(item),
+            }
+            for item in items
+        ]
+
+        async with self._session_factory() as sess:
+            async with sess.begin():
+                # Ensure the parent session row exists - use merge for cross-DB compatibility
+                # Check if session exists
+                existing = await sess.execute(
+                    select(self._sessions.c.session_id).where(
+                        self._sessions.c.session_id == self.session_id
+                    )
+                )
+                if not existing.scalar_one_or_none():
+                    # Session doesn't exist, create it
+                    await sess.execute(
+                        insert(self._sessions).values({"session_id": self.session_id})
+                    )
+
+                # Insert messages in bulk
+                await sess.execute(insert(self._messages), payload)
+
+                # Touch updated_at column
+                await sess.execute(
+                    update(self._sessions)
+                    .where(self._sessions.c.session_id == self.session_id)
+                    .values(updated_at=sql_text("CURRENT_TIMESTAMP"))
+                )
+
+    async def pop_item(self) -> TResponseInputItem | None:
+        """Remove and return the most recent item from the session.
+
+        Returns:
+            The most recent item if it exists, None if the session is empty
+        """
+        await self._ensure_tables()
+        async with self._session_factory() as sess:
+            async with sess.begin():
+                # Fallback for all dialects - get ID first, then delete
+                subq = (
+                    select(self._messages.c.id)
+                    .where(self._messages.c.session_id == self.session_id)
+                    .order_by(self._messages.c.created_at.desc())
+                    .limit(1)
+                )
+                res = await sess.execute(subq)
+                row_id = res.scalar_one_or_none()
+                if row_id is None:
+                    return None
+                # Fetch data before deleting
+                res_data = await sess.execute(
+                    select(self._messages.c.message_data).where(self._messages.c.id == row_id)
+                )
+                row = res_data.scalar_one_or_none()
+                await sess.execute(delete(self._messages).where(self._messages.c.id == row_id))
+
+                if row is None:
+                    return None
+                try:
+                    return await self._deserialize_item(row)
+                except json.JSONDecodeError:
+                    return None
+
+    async def clear_session(self) -> None:
+        """Clear all items for this session."""
+        await self._ensure_tables()
+        async with self._session_factory() as sess:
+            async with sess.begin():
+                await sess.execute(
+                    delete(self._messages).where(self._messages.c.session_id == self.session_id)
+                )
+                await sess.execute(
+                    delete(self._sessions).where(self._sessions.c.session_id == self.session_id)
+                )

agents/extensions/models/litellm_model.py

@@ -3,6 +3,7 @@ from __future__ import annotations
 import json
 import time
 from collections.abc import AsyncIterator
+from copy import copy
 from typing import Any, Literal, cast, overload
 
 from openai.types.responses.response_usage import InputTokensDetails, OutputTokensDetails
@@ -20,6 +21,7 @@ except ImportError as _e:
 from openai import NOT_GIVEN, AsyncStream, NotGiven
 from openai.types.chat import (
     ChatCompletionChunk,
+    ChatCompletionMessageCustomToolCall,
     ChatCompletionMessageFunctionToolCall,
 )
 from openai.types.chat.chat_completion_message import (
@@ -28,7 +30,6 @@ from openai.types.chat.chat_completion_message import (
     ChatCompletionMessage,
 )
 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
@@ -82,7 +83,8 @@ class LitellmModel(Model):
         output_schema: AgentOutputSchemaBase | None,
         handoffs: list[Handoff],
         tracing: ModelTracing,
-        previous_response_id: str | None,
+        previous_response_id: str | None = None,  # unused
+        conversation_id: str | None = None,  # unused
         prompt: Any | None = None,
     ) -> ModelResponse:
         with generation_span(
@@ -171,7 +173,8 @@ class LitellmModel(Model):
         output_schema: AgentOutputSchemaBase | None,
         handoffs: list[Handoff],
         tracing: ModelTracing,
-        previous_response_id: str | None,
+        previous_response_id: str | None = None,  # unused
+        conversation_id: str | None = None,  # unused
         prompt: Any | None = None,
     ) -> AsyncIterator[TResponseStreamEvent]:
         with generation_span(
@@ -300,9 +303,9 @@ class LitellmModel(Model):
 
         extra_kwargs = {}
         if model_settings.extra_query:
-            extra_kwargs["extra_query"] = model_settings.extra_query
+            extra_kwargs["extra_query"] = copy(model_settings.extra_query)
         if model_settings.metadata:
-            extra_kwargs["metadata"] = model_settings.metadata
+            extra_kwargs["metadata"] = copy(model_settings.metadata)
         if model_settings.extra_body and isinstance(model_settings.extra_body, dict):
             extra_kwargs.update(model_settings.extra_body)
 
@@ -366,7 +369,9 @@ class LitellmConverter:
         if message.role != "assistant":
             raise ModelBehaviorError(f"Unsupported role: {message.role}")
 
-        tool_calls: list[ChatCompletionMessageToolCall] | 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

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

@@ -291,7 +291,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 +309,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/handoffs.py

@@ -119,9 +119,9 @@ class Handoff(Generic[TContext, TAgent]):
     True, as it increases the likelihood of correct JSON input.
     """
 
-    is_enabled: bool | Callable[
-        [RunContextWrapper[Any], AgentBase[Any]], MaybeAwaitable[bool]
-    ] = True
+    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."""

agents/lifecycle.py

@@ -1,8 +1,9 @@
-from typing import Any, Generic
+from typing import Any, Generic, Optional
 
 from typing_extensions import TypeVar
 
 from .agent import Agent, AgentBase
+from .items import ModelResponse, TResponseInputItem
 from .run_context import RunContextWrapper, TContext
 from .tool import Tool
 
@@ -14,6 +15,25 @@ class RunHooksBase(Generic[TContext, TAgent]):
     override the methods you need.
     """
 
+    async def on_llm_start(
+        self,
+        context: RunContextWrapper[TContext],
+        agent: Agent[TContext],
+        system_prompt: Optional[str],
+        input_items: list[TResponseInputItem],
+    ) -> None:
+        """Called just before invoking the LLM for this agent."""
+        pass
+
+    async def on_llm_end(
+        self,
+        context: RunContextWrapper[TContext],
+        agent: Agent[TContext],
+        response: ModelResponse,
+    ) -> None:
+        """Called immediately after the LLM call returns for this agent."""
+        pass
+
     async def on_agent_start(self, context: RunContextWrapper[TContext], agent: TAgent) -> None:
         """Called before the agent is invoked. Called each time the current agent changes."""
         pass
@@ -106,6 +126,25 @@ class AgentHooksBase(Generic[TContext, TAgent]):
         """Called after a tool is invoked."""
         pass
 
+    async def on_llm_start(
+        self,
+        context: RunContextWrapper[TContext],
+        agent: Agent[TContext],
+        system_prompt: Optional[str],
+        input_items: list[TResponseInputItem],
+    ) -> None:
+        """Called immediately before the agent issues an LLM call."""
+        pass
+
+    async def on_llm_end(
+        self,
+        context: RunContextWrapper[TContext],
+        agent: Agent[TContext],
+        response: ModelResponse,
+    ) -> None:
+        """Called immediately after the agent receives the LLM response."""
+        pass
+
 
 RunHooks = RunHooksBase[TContext, Agent]
 """Run hooks when using `Agent`."""