openai-agents 0.2.7__py3-none-any.whl → 0.2.9__py3-none-any.whl

agents/_run_impl.py

@@ -961,7 +961,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
 

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,298 @@
+"""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",
+    ):  # noqa: D401 – short description on the class-level docstring
+        """Create a new session.
+
+        Parameters
+        ----------
+        session_id
+            Unique identifier for the conversation.
+        engine
+            A pre-configured SQLAlchemy *async* engine.  The engine **must** be
+            created with an async driver (``postgresql+asyncpg://``,
+            ``mysql+aiomysql://`` or ``sqlite+aiosqlite://``).
+        create_tables
+            Whether to automatically create the required tables & indexes.
+            Defaults to *False* for production use. Set to *True* for development
+            and testing when migrations aren't used.
+        sessions_table, messages_table
+            Override default table names 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.
+
+        Parameters
+        ----------
+        session_id
+            Conversation ID.
+        url
+            Any SQLAlchemy async URL – e.g. ``"postgresql+asyncpg://user:pass@host/db"``.
+        engine_kwargs
+            Additional kwargs forwarded to :pyfunc:`sqlalchemy.ext.asyncio.create_async_engine`.
+        kwargs
+            Forwarded to the main constructor (``create_tables``, custom table names, …).
+        """
+        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]:
+        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:
+        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:
+        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:  # noqa: D401 – imperative mood is fine
+        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

@@ -20,6 +20,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 +29,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
@@ -366,7 +366,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/items.py

@@ -1,7 +1,6 @@
 from __future__ import annotations
 
 import abc
-import copy
 from dataclasses import dataclass
 from typing import TYPE_CHECKING, Any, Generic, Literal, TypeVar, Union
 
@@ -277,7 +276,7 @@ class ItemHelpers:
                     "role": "user",
                 }
             ]
-        return copy.deepcopy(input)
+        return input.copy()
 
     @classmethod
     def text_message_outputs(cls, items: list[RunItem]) -> str:

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`."""