openai-agents 0.0.19__py3-none-any.whl → 0.2.0__py3-none-any.whl

agents/run.py

@@ -2,6 +2,7 @@ from __future__ import annotations
 
 import asyncio
 import copy
+import inspect
 from dataclasses import dataclass, field
 from typing import Any, Generic, cast
 
@@ -31,6 +32,7 @@ from .exceptions import (
     ModelBehaviorError,
     OutputGuardrailTripwireTriggered,
     RunErrorDetails,
+    UserError,
 )
 from .guardrail import (
     InputGuardrail,
@@ -42,6 +44,7 @@ from .handoffs import Handoff, HandoffInputFilter, handoff
 from .items import ItemHelpers, ModelResponse, RunItem, TResponseInputItem
 from .lifecycle import RunHooks
 from .logger import logger
+from .memory import Session
 from .model_settings import ModelSettings
 from .models.interface import Model, ModelProvider
 from .models.multi_provider import MultiProvider
@@ -155,6 +158,9 @@ class RunOptions(TypedDict, Generic[TContext]):
     previous_response_id: NotRequired[str | None]
     """The ID of the previous response, if any."""
 
+    session: NotRequired[Session | None]
+    """The session for the run."""
+
 
 class Runner:
     @classmethod
@@ -168,6 +174,7 @@ class Runner:
         hooks: RunHooks[TContext] | None = None,
         run_config: RunConfig | None = None,
         previous_response_id: str | None = None,
+        session: Session | None = None,
     ) -> RunResult:
         """Run a workflow starting at the given agent. The agent will run in a loop until a final
         output is generated. The loop runs like so:
@@ -204,6 +211,7 @@ class Runner:
             hooks=hooks,
             run_config=run_config,
             previous_response_id=previous_response_id,
+            session=session,
         )
 
     @classmethod
@@ -217,6 +225,7 @@ class Runner:
         hooks: RunHooks[TContext] | None = None,
         run_config: RunConfig | None = None,
         previous_response_id: str | None = None,
+        session: Session | None = None,
     ) -> RunResult:
         """Run a workflow synchronously, starting at the given agent. Note that this just wraps the
         `run` method, so it will not work if there's already an event loop (e.g. inside an async
@@ -256,6 +265,7 @@ class Runner:
             hooks=hooks,
             run_config=run_config,
             previous_response_id=previous_response_id,
+            session=session,
         )
 
     @classmethod
@@ -268,6 +278,7 @@ class Runner:
         hooks: RunHooks[TContext] | None = None,
         run_config: RunConfig | None = None,
         previous_response_id: str | None = None,
+        session: Session | None = None,
     ) -> RunResultStreaming:
         """Run a workflow starting at the given agent in streaming mode. The returned result object
         contains a method you can use to stream semantic events as they are generated.
@@ -304,6 +315,7 @@ class Runner:
             hooks=hooks,
             run_config=run_config,
             previous_response_id=previous_response_id,
+            session=session,
         )
 
 
@@ -324,11 +336,15 @@ class AgentRunner:
         hooks = kwargs.get("hooks")
         run_config = kwargs.get("run_config")
         previous_response_id = kwargs.get("previous_response_id")
+        session = kwargs.get("session")
         if hooks is None:
             hooks = RunHooks[Any]()
         if run_config is None:
             run_config = RunConfig()
 
+        # Prepare input with session if enabled
+        prepared_input = await self._prepare_input_with_session(input, session)
+
         tool_use_tracker = AgentToolUseTracker()
 
         with TraceCtxManager(
@@ -339,7 +355,7 @@ class AgentRunner:
             disabled=run_config.tracing_disabled,
         ):
             current_turn = 0
-            original_input: str | list[TResponseInputItem] = copy.deepcopy(input)
+            original_input: str | list[TResponseInputItem] = copy.deepcopy(prepared_input)
             generated_items: list[RunItem] = []
             model_responses: list[ModelResponse] = []
 
@@ -361,7 +377,8 @@ class AgentRunner:
                     # agent changes, or if the agent loop ends.
                     if current_span is None:
                         handoff_names = [
-                            h.agent_name for h in AgentRunner._get_handoffs(current_agent)
+                            h.agent_name
+                            for h in await AgentRunner._get_handoffs(current_agent, context_wrapper)
                         ]
                         if output_schema := AgentRunner._get_output_schema(current_agent):
                             output_type_name = output_schema.name()
@@ -397,7 +414,7 @@ class AgentRunner:
                                 starting_agent,
                                 starting_agent.input_guardrails
                                 + (run_config.input_guardrails or []),
-                                copy.deepcopy(input),
+                                copy.deepcopy(prepared_input),
                                 context_wrapper,
                             ),
                             self._run_single_turn(
@@ -439,7 +456,7 @@ class AgentRunner:
                             turn_result.next_step.output,
                             context_wrapper,
                         )
-                        return RunResult(
+                        result = RunResult(
                             input=original_input,
                             new_items=generated_items,
                             raw_responses=model_responses,
@@ -449,6 +466,11 @@ class AgentRunner:
                             output_guardrail_results=output_guardrail_results,
                             context_wrapper=context_wrapper,
                         )
+
+                        # Save the conversation to session if enabled
+                        await self._save_result_to_session(session, input, result)
+
+                        return result
                     elif isinstance(turn_result.next_step, NextStepHandoff):
                         current_agent = cast(Agent[TContext], turn_result.next_step.new_agent)
                         current_span.finish(reset_current=True)
@@ -486,10 +508,13 @@ class AgentRunner:
         hooks = kwargs.get("hooks")
         run_config = kwargs.get("run_config")
         previous_response_id = kwargs.get("previous_response_id")
+        session = kwargs.get("session")
+
         return asyncio.get_event_loop().run_until_complete(
             self.run(
                 starting_agent,
                 input,
+                session=session,
                 context=context,
                 max_turns=max_turns,
                 hooks=hooks,
@@ -509,6 +534,8 @@ class AgentRunner:
         hooks = kwargs.get("hooks")
         run_config = kwargs.get("run_config")
         previous_response_id = kwargs.get("previous_response_id")
+        session = kwargs.get("session")
+
         if hooks is None:
             hooks = RunHooks[Any]()
         if run_config is None:
@@ -561,6 +588,7 @@ class AgentRunner:
                 context_wrapper=context_wrapper,
                 run_config=run_config,
                 previous_response_id=previous_response_id,
+                session=session,
             )
         )
         return streamed_result
@@ -619,6 +647,7 @@ class AgentRunner:
         context_wrapper: RunContextWrapper[TContext],
         run_config: RunConfig,
         previous_response_id: str | None,
+        session: Session | None,
     ):
         if streamed_result.trace:
             streamed_result.trace.start(mark_as_current=True)
@@ -632,6 +661,12 @@ class AgentRunner:
         streamed_result._event_queue.put_nowait(AgentUpdatedStreamEvent(new_agent=current_agent))
 
         try:
+            # Prepare input with session if enabled
+            prepared_input = await AgentRunner._prepare_input_with_session(starting_input, session)
+
+            # Update the streamed result with the prepared input
+            streamed_result.input = prepared_input
+
             while True:
                 if streamed_result.is_complete:
                     break
@@ -641,7 +676,10 @@ class AgentRunner:
                 # Start an agent span if we don't have one. This span is ended if the current
                 # agent changes, or if the agent loop ends.
                 if current_span is None:
-                    handoff_names = [h.agent_name for h in cls._get_handoffs(current_agent)]
+                    handoff_names = [
+                        h.agent_name
+                        for h in await cls._get_handoffs(current_agent, context_wrapper)
+                    ]
                     if output_schema := cls._get_output_schema(current_agent):
                         output_type_name = output_schema.name()
                     else:
@@ -675,7 +713,7 @@ class AgentRunner:
                         cls._run_input_guardrails_with_queue(
                             starting_agent,
                             starting_agent.input_guardrails + (run_config.input_guardrails or []),
-                            copy.deepcopy(ItemHelpers.input_to_new_input_list(starting_input)),
+                            copy.deepcopy(ItemHelpers.input_to_new_input_list(prepared_input)),
                             context_wrapper,
                             streamed_result,
                             current_span,
@@ -729,6 +767,23 @@ class AgentRunner:
                         streamed_result.output_guardrail_results = output_guardrail_results
                         streamed_result.final_output = turn_result.next_step.output
                         streamed_result.is_complete = True
+
+                        # Save the conversation to session if enabled
+                        # Create a temporary RunResult for session saving
+                        temp_result = RunResult(
+                            input=streamed_result.input,
+                            new_items=streamed_result.new_items,
+                            raw_responses=streamed_result.raw_responses,
+                            final_output=streamed_result.final_output,
+                            _last_agent=current_agent,
+                            input_guardrail_results=streamed_result.input_guardrail_results,
+                            output_guardrail_results=streamed_result.output_guardrail_results,
+                            context_wrapper=context_wrapper,
+                        )
+                        await AgentRunner._save_result_to_session(
+                            session, starting_input, temp_result
+                        )
+
                         streamed_result._event_queue.put_nowait(QueueCompleteSentinel())
                     elif isinstance(turn_result.next_step, NextStepRunAgain):
                         pass
@@ -798,7 +853,7 @@ class AgentRunner:
             agent.get_prompt(context_wrapper),
         )
 
-        handoffs = cls._get_handoffs(agent)
+        handoffs = await cls._get_handoffs(agent, context_wrapper)
         model = cls._get_model(agent, run_config)
         model_settings = agent.model_settings.resolve(run_config.model_settings)
         model_settings = RunImpl.maybe_reset_tool_choice(agent, tool_use_tracker, model_settings)
@@ -898,7 +953,7 @@ class AgentRunner:
         )
 
         output_schema = cls._get_output_schema(agent)
-        handoffs = cls._get_handoffs(agent)
+        handoffs = await cls._get_handoffs(agent, context_wrapper)
         input = ItemHelpers.input_to_new_input_list(original_input)
         input.extend([generated_item.to_input_item() for generated_item in generated_items])
 
@@ -1091,14 +1146,28 @@ class AgentRunner:
         return AgentOutputSchema(agent.output_type)
 
     @classmethod
-    def _get_handoffs(cls, agent: Agent[Any]) -> list[Handoff]:
+    async def _get_handoffs(
+        cls, agent: Agent[Any], context_wrapper: RunContextWrapper[Any]
+    ) -> list[Handoff]:
         handoffs = []
         for handoff_item in agent.handoffs:
             if isinstance(handoff_item, Handoff):
                 handoffs.append(handoff_item)
             elif isinstance(handoff_item, Agent):
                 handoffs.append(handoff(handoff_item))
-        return handoffs
+
+        async def _check_handoff_enabled(handoff_obj: Handoff) -> bool:
+            attr = handoff_obj.is_enabled
+            if isinstance(attr, bool):
+                return attr
+            res = attr(context_wrapper, agent)
+            if inspect.isawaitable(res):
+                return bool(await res)
+            return bool(res)
+
+        results = await asyncio.gather(*(_check_handoff_enabled(h) for h in handoffs))
+        enabled: list[Handoff] = [h for h, ok in zip(handoffs, results) if ok]
+        return enabled
 
     @classmethod
     async def _get_all_tools(
@@ -1117,5 +1186,57 @@ class AgentRunner:
 
         return run_config.model_provider.get_model(agent.model)
 
+    @classmethod
+    async def _prepare_input_with_session(
+        cls,
+        input: str | list[TResponseInputItem],
+        session: Session | None,
+    ) -> str | list[TResponseInputItem]:
+        """Prepare input by combining it with session history if enabled."""
+        if session is None:
+            return input
+
+        # Validate that we don't have both a session and a list input, as this creates
+        # ambiguity about whether the list should append to or replace existing session history
+        if isinstance(input, list):
+            raise UserError(
+                "Cannot provide both a session and a list of input items. "
+                "When using session memory, provide only a string input to append to the "
+                "conversation, or use session=None and provide a list to manually manage "
+                "conversation history."
+            )
+
+        # Get previous conversation history
+        history = await session.get_items()
+
+        # Convert input to list format
+        new_input_list = ItemHelpers.input_to_new_input_list(input)
+
+        # Combine history with new input
+        combined_input = history + new_input_list
+
+        return combined_input
+
+    @classmethod
+    async def _save_result_to_session(
+        cls,
+        session: Session | None,
+        original_input: str | list[TResponseInputItem],
+        result: RunResult,
+    ) -> None:
+        """Save the conversation turn to session."""
+        if session is None:
+            return
+
+        # Convert original input to list format if needed
+        input_list = ItemHelpers.input_to_new_input_list(original_input)
+
+        # Convert new items to input format
+        new_items_as_input = [item.to_input_item() for item in result.new_items]
+
+        # Save all items from this turn
+        items_to_save = input_list + new_items_as_input
+        await session.add_items(items_to_save)
+
 
 DEFAULT_AGENT_RUNNER = AgentRunner()

agents/tool.py

@@ -7,6 +7,10 @@ from dataclasses import dataclass
 from typing import TYPE_CHECKING, Any, Callable, Literal, Union, overload
 
 from openai.types.responses.file_search_tool_param import Filters, RankingOptions
+from openai.types.responses.response_computer_tool_call import (
+    PendingSafetyCheck,
+    ResponseComputerToolCall,
+)
 from openai.types.responses.response_output_item import LocalShellCall, McpApprovalRequest
 from openai.types.responses.tool_param import CodeInterpreter, ImageGeneration, Mcp
 from openai.types.responses.web_search_tool_param import UserLocation
@@ -26,7 +30,7 @@ from .util import _error_tracing
 from .util._types import MaybeAwaitable
 
 if TYPE_CHECKING:
-    from .agent import Agent
+    from .agent import Agent, AgentBase
 
 ToolParams = ParamSpec("ToolParams")
 
@@ -83,7 +87,7 @@ class FunctionTool:
     """Whether the JSON schema is in strict mode. We **strongly** recommend setting this to True,
     as it increases the likelihood of correct JSON input."""
 
-    is_enabled: bool | Callable[[RunContextWrapper[Any], Agent[Any]], MaybeAwaitable[bool]] = True
+    is_enabled: bool | Callable[[RunContextWrapper[Any], AgentBase], MaybeAwaitable[bool]] = True
     """Whether the tool is enabled. Either a bool or a Callable that takes the run context and agent
     and returns whether the tool is enabled. You can use this to dynamically enable/disable a tool
     based on your context/state."""
@@ -141,11 +145,31 @@ class ComputerTool:
     as well as implements the computer actions like click, screenshot, etc.
     """
 
+    on_safety_check: Callable[[ComputerToolSafetyCheckData], MaybeAwaitable[bool]] | None = None
+    """Optional callback to acknowledge computer tool safety checks."""
+
     @property
     def name(self):
         return "computer_use_preview"
 
 
+@dataclass
+class ComputerToolSafetyCheckData:
+    """Information about a computer tool safety check."""
+
+    ctx_wrapper: RunContextWrapper[Any]
+    """The run context."""
+
+    agent: Agent[Any]
+    """The agent performing the computer action."""
+
+    tool_call: ResponseComputerToolCall
+    """The computer tool call."""
+
+    safety_check: PendingSafetyCheck
+    """The pending safety check to acknowledge."""
+
+
 @dataclass
 class MCPToolApprovalRequest:
     """A request to approve a tool call."""
@@ -176,7 +200,7 @@ MCPToolApprovalFunction = Callable[
 @dataclass
 class HostedMCPTool:
     """A tool that allows the LLM to use a remote MCP server. The LLM will automatically list and
-    call tools, without requiring a a round trip back to your code.
+    call tools, without requiring a round trip back to your code.
     If you want to run MCP servers locally via stdio, in a VPC or other non-publicly-accessible
     environment, or you just prefer to run tool calls locally, then you can instead use the servers
     in `agents.mcp` and pass `Agent(mcp_servers=[...])` to the agent."""
@@ -276,7 +300,7 @@ def function_tool(
     use_docstring_info: bool = True,
     failure_error_function: ToolErrorFunction | None = None,
     strict_mode: bool = True,
-    is_enabled: bool | Callable[[RunContextWrapper[Any], Agent[Any]], MaybeAwaitable[bool]] = True,
+    is_enabled: bool | Callable[[RunContextWrapper[Any], AgentBase], MaybeAwaitable[bool]] = True,
 ) -> FunctionTool:
     """Overload for usage as @function_tool (no parentheses)."""
     ...
@@ -291,7 +315,7 @@ def function_tool(
     use_docstring_info: bool = True,
     failure_error_function: ToolErrorFunction | None = None,
     strict_mode: bool = True,
-    is_enabled: bool | Callable[[RunContextWrapper[Any], Agent[Any]], MaybeAwaitable[bool]] = True,
+    is_enabled: bool | Callable[[RunContextWrapper[Any], AgentBase], MaybeAwaitable[bool]] = True,
 ) -> Callable[[ToolFunction[...]], FunctionTool]:
     """Overload for usage as @function_tool(...)."""
     ...
@@ -306,7 +330,7 @@ def function_tool(
     use_docstring_info: bool = True,
     failure_error_function: ToolErrorFunction | None = default_tool_error_function,
     strict_mode: bool = True,
-    is_enabled: bool | Callable[[RunContextWrapper[Any], Agent[Any]], MaybeAwaitable[bool]] = True,
+    is_enabled: bool | Callable[[RunContextWrapper[Any], AgentBase], MaybeAwaitable[bool]] = True,
 ) -> FunctionTool | Callable[[ToolFunction[...]], FunctionTool]:
     """
     Decorator to create a FunctionTool from a function. By default, we will:

agents/tool_context.py

@@ -1,5 +1,7 @@
 from dataclasses import dataclass, field, fields
-from typing import Any
+from typing import Any, Optional
+
+from openai.types.responses import ResponseFunctionToolCall
 
 from .run_context import RunContextWrapper, TContext
 
@@ -8,16 +10,26 @@ def _assert_must_pass_tool_call_id() -> str:
     raise ValueError("tool_call_id must be passed to ToolContext")
 
 
+def _assert_must_pass_tool_name() -> str:
+    raise ValueError("tool_name must be passed to ToolContext")
+
+
 @dataclass
 class ToolContext(RunContextWrapper[TContext]):
     """The context of a tool call."""
 
+    tool_name: str = field(default_factory=_assert_must_pass_tool_name)
+    """The name of the tool being invoked."""
+
     tool_call_id: str = field(default_factory=_assert_must_pass_tool_call_id)
     """The ID of the tool call."""
 
     @classmethod
     def from_agent_context(
-        cls, context: RunContextWrapper[TContext], tool_call_id: str
+        cls,
+        context: RunContextWrapper[TContext],
+        tool_call_id: str,
+        tool_call: Optional[ResponseFunctionToolCall] = None,
     ) -> "ToolContext":
         """
         Create a ToolContext from a RunContextWrapper.
@@ -26,4 +38,5 @@ class ToolContext(RunContextWrapper[TContext]):
         base_values: dict[str, Any] = {
             f.name: getattr(context, f.name) for f in fields(RunContextWrapper) if f.init
         }
-        return cls(tool_call_id=tool_call_id, **base_values)
+        tool_name = tool_call.name if tool_call is not None else _assert_must_pass_tool_name()
+        return cls(tool_name=tool_name, tool_call_id=tool_call_id, **base_values)

agents/tracing/__init__.py

@@ -1,7 +1,5 @@
 import atexit
 
-from agents.tracing.provider import DefaultTraceProvider, TraceProvider
-
 from .create import (
     agent_span,
     custom_span,
@@ -20,6 +18,7 @@ from .create import (
 )
 from .processor_interface import TracingProcessor
 from .processors import default_exporter, default_processor
+from .provider import DefaultTraceProvider, TraceProvider
 from .setup import get_trace_provider, set_trace_provider
 from .span_data import (
     AgentSpanData,

agents/tracing/processor_interface.py

@@ -23,7 +23,7 @@ class TracingProcessor(abc.ABC):
         """Called when a trace is finished.
 
         Args:
-            trace: The trace that started.
+            trace: The trace that finished.
         """
         pass
 

agents/voice/models/openai_stt.py

@@ -226,7 +226,7 @@ class OpenAISTTTranscriptionSession(StreamedTranscriptionSession):
                     break
 
                 event_type = event.get("type", "unknown")
-                if event_type == "conversation.item.input_audio_transcription.completed":
+                if event_type == "input_audio_transcription_completed":
                     transcript = cast(str, event.get("transcript", ""))
                     if len(transcript) > 0:
                         self._end_turn(transcript)

agents/voice/pipeline.py

@@ -125,6 +125,12 @@ class VoicePipeline:
                 self._get_tts_model(), self.config.tts_settings, self.config
             )
 
+            try:
+                async for intro_text in self.workflow.on_start():
+                    await output._add_text(intro_text)
+            except Exception as e:
+                logger.warning(f"on_start() failed: {e}")
+
             transcription_session = await self._get_stt_model().create_session(
                 audio_input,
                 self.config.stt_settings,

agents/voice/workflow.py

@@ -32,6 +32,14 @@ class VoiceWorkflowBase(abc.ABC):
         """
         pass
 
+    async def on_start(self) -> AsyncIterator[str]:
+        """
+        Optional method that runs before any user input is received. Can be used
+        to deliver a greeting or instruction via TTS. Defaults to doing nothing.
+        """
+        return
+        yield
+
 
 class VoiceWorkflowHelper:
     @classmethod