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

agents/agent.py

@@ -13,21 +13,38 @@ from typing_extensions import NotRequired, TypeAlias, TypedDict
 from .agent_output import AgentOutputSchemaBase
 from .guardrail import InputGuardrail, OutputGuardrail
 from .handoffs import Handoff
-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
-from .tool import FunctionTool, FunctionToolResult, Tool, function_tool
+from .tool import (
+    FunctionTool,
+    FunctionToolResult,
+    Tool,
+    ToolErrorFunction,
+    default_tool_error_function,
+    function_tool,
+)
+from .tool_context import ToolContext
 from .util import _transforms
 from .util._types import MaybeAwaitable
 
 if TYPE_CHECKING:
-    from .lifecycle import AgentHooks
+    from openai.types.responses.response_function_tool_call import ResponseFunctionToolCall
+
+    from .lifecycle import AgentHooks, RunHooks
     from .mcp import MCPServer
-    from .result import RunResult
+    from .memory.session import Session
+    from .result import RunResult, RunResultStreaming
+    from .run import RunConfig
+    from .stream_events import StreamEvent
 
 
 @dataclass
@@ -52,6 +69,19 @@ ToolsToFinalOutputFunction: TypeAlias = Callable[
 """
 
 
+class AgentToolStreamEvent(TypedDict):
+    """Streaming event emitted when an agent is invoked as a tool."""
+
+    event: StreamEvent
+    """The streaming event from the nested agent run."""
+
+    agent: Agent[Any]
+    """The nested agent emitting the event."""
+
+    tool_call: ResponseFunctionToolCall | None
+    """The originating tool call, if available."""
+
+
 class StopAtTools(TypedDict):
     stop_at_tool_names: list[str]
     """A list of tool names, any of which will stop the agent from running further."""
@@ -168,10 +198,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 +235,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 +316,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__}"
@@ -355,7 +406,19 @@ class Agent(AgentBase, Generic[TContext]):
         self,
         tool_name: str | None,
         tool_description: str | None,
-        custom_output_extractor: Callable[[RunResult], Awaitable[str]] | None = None,
+        custom_output_extractor: (
+            Callable[[RunResult | RunResultStreaming], Awaitable[str]] | None
+        ) = None,
+        is_enabled: bool
+        | Callable[[RunContextWrapper[Any], AgentBase[Any]], MaybeAwaitable[bool]] = True,
+        on_stream: Callable[[AgentToolStreamEvent], MaybeAwaitable[None]] | None = None,
+        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,
+        failure_error_function: ToolErrorFunction | None = default_tool_error_function,
     ) -> Tool:
         """Transform this agent into a tool, callable by other agents.
 
@@ -371,24 +434,106 @@ 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.
+            on_stream: Optional callback (sync or async) to receive streaming events from the nested
+                agent run. The callback receives an `AgentToolStreamEvent` containing the nested
+                agent, the originating tool call (when available), and each stream event. When
+                provided, the nested agent is executed in streaming mode.
+            failure_error_function: If provided, generate an error message when the tool (agent) run
+                fails. The message is sent to the LLM. If None, the exception is raised instead.
         """
 
         @function_tool(
             name_override=tool_name or _transforms.transform_string_function_style(self.name),
             description_override=tool_description or "",
+            is_enabled=is_enabled,
+            failure_error_function=failure_error_function,
         )
-        async def run_agent(context: RunContextWrapper, input: str) -> str:
-            from .run import Runner
-
-            output = await Runner.run(
-                starting_agent=self,
-                input=input,
-                context=context.context,
-            )
+        async def run_agent(context: ToolContext, input: str) -> Any:
+            from .run import DEFAULT_MAX_TURNS, Runner
+
+            resolved_max_turns = max_turns if max_turns is not None else DEFAULT_MAX_TURNS
+            run_result: RunResult | RunResultStreaming
+
+            if on_stream is not None:
+                run_result = Runner.run_streamed(
+                    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,
+                )
+                # Dispatch callbacks in the background so slow handlers do not block
+                # event consumption.
+                event_queue: asyncio.Queue[AgentToolStreamEvent | None] = asyncio.Queue()
+
+                async def _run_handler(payload: AgentToolStreamEvent) -> None:
+                    """Execute the user callback while capturing exceptions."""
+                    try:
+                        maybe_result = on_stream(payload)
+                        if inspect.isawaitable(maybe_result):
+                            await maybe_result
+                    except Exception:
+                        logger.exception(
+                            "Error while handling on_stream event for agent tool %s.",
+                            self.name,
+                        )
+
+                async def dispatch_stream_events() -> None:
+                    while True:
+                        payload = await event_queue.get()
+                        is_sentinel = payload is None  # None marks the end of the stream.
+                        try:
+                            if payload is not None:
+                                await _run_handler(payload)
+                        finally:
+                            event_queue.task_done()
+
+                        if is_sentinel:
+                            break
+
+                dispatch_task = asyncio.create_task(dispatch_stream_events())
+
+                try:
+                    from .stream_events import AgentUpdatedStreamEvent
+
+                    current_agent = run_result.current_agent
+                    async for event in run_result.stream_events():
+                        if isinstance(event, AgentUpdatedStreamEvent):
+                            current_agent = event.new_agent
+
+                        payload: AgentToolStreamEvent = {
+                            "event": event,
+                            "agent": current_agent,
+                            "tool_call": context.tool_call,
+                        }
+                        await event_queue.put(payload)
+                finally:
+                    await event_queue.put(None)
+                    await event_queue.join()
+                    await dispatch_task
+            else:
+                run_result = 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)
+                return await custom_output_extractor(run_result)
 
-            return ItemHelpers.text_message_outputs(output.new_items)
+            return run_result.final_output
 
         return run_agent
 

agents/apply_diff.py

@@ -0,0 +1,329 @@
+"""Utility for applying V4A diffs against text inputs."""
+
+from __future__ import annotations
+
+import re
+from collections.abc import Sequence
+from dataclasses import dataclass
+from typing import Callable, Literal
+
+ApplyDiffMode = Literal["default", "create"]
+
+
+@dataclass
+class Chunk:
+    orig_index: int
+    del_lines: list[str]
+    ins_lines: list[str]
+
+
+@dataclass
+class ParserState:
+    lines: list[str]
+    index: int = 0
+    fuzz: int = 0
+
+
+@dataclass
+class ParsedUpdateDiff:
+    chunks: list[Chunk]
+    fuzz: int
+
+
+@dataclass
+class ReadSectionResult:
+    next_context: list[str]
+    section_chunks: list[Chunk]
+    end_index: int
+    eof: bool
+
+
+END_PATCH = "*** End Patch"
+END_FILE = "*** End of File"
+SECTION_TERMINATORS = [
+    END_PATCH,
+    "*** Update File:",
+    "*** Delete File:",
+    "*** Add File:",
+]
+END_SECTION_MARKERS = [*SECTION_TERMINATORS, END_FILE]
+
+
+def apply_diff(input: str, diff: str, mode: ApplyDiffMode = "default") -> str:
+    """Apply a V4A diff to the provided text.
+
+    This parser understands both the create-file syntax (only "+" prefixed
+    lines) and the default update syntax that includes context hunks.
+    """
+
+    diff_lines = _normalize_diff_lines(diff)
+    if mode == "create":
+        return _parse_create_diff(diff_lines)
+
+    parsed = _parse_update_diff(diff_lines, input)
+    return _apply_chunks(input, parsed.chunks)
+
+
+def _normalize_diff_lines(diff: str) -> list[str]:
+    lines = [line.rstrip("\r") for line in re.split(r"\r?\n", diff)]
+    if lines and lines[-1] == "":
+        lines.pop()
+    return lines
+
+
+def _is_done(state: ParserState, prefixes: Sequence[str]) -> bool:
+    if state.index >= len(state.lines):
+        return True
+    if any(state.lines[state.index].startswith(prefix) for prefix in prefixes):
+        return True
+    return False
+
+
+def _read_str(state: ParserState, prefix: str) -> str:
+    if state.index >= len(state.lines):
+        return ""
+    current = state.lines[state.index]
+    if current.startswith(prefix):
+        state.index += 1
+        return current[len(prefix) :]
+    return ""
+
+
+def _parse_create_diff(lines: list[str]) -> str:
+    parser = ParserState(lines=[*lines, END_PATCH])
+    output: list[str] = []
+
+    while not _is_done(parser, SECTION_TERMINATORS):
+        if parser.index >= len(parser.lines):
+            break
+        line = parser.lines[parser.index]
+        parser.index += 1
+        if not line.startswith("+"):
+            raise ValueError(f"Invalid Add File Line: {line}")
+        output.append(line[1:])
+
+    return "\n".join(output)
+
+
+def _parse_update_diff(lines: list[str], input: str) -> ParsedUpdateDiff:
+    parser = ParserState(lines=[*lines, END_PATCH])
+    input_lines = input.split("\n")
+    chunks: list[Chunk] = []
+    cursor = 0
+
+    while not _is_done(parser, END_SECTION_MARKERS):
+        anchor = _read_str(parser, "@@ ")
+        has_bare_anchor = (
+            anchor == "" and parser.index < len(parser.lines) and parser.lines[parser.index] == "@@"
+        )
+        if has_bare_anchor:
+            parser.index += 1
+
+        if not (anchor or has_bare_anchor or cursor == 0):
+            current_line = parser.lines[parser.index] if parser.index < len(parser.lines) else ""
+            raise ValueError(f"Invalid Line:\n{current_line}")
+
+        if anchor.strip():
+            cursor = _advance_cursor_to_anchor(anchor, input_lines, cursor, parser)
+
+        section = _read_section(parser.lines, parser.index)
+        find_result = _find_context(input_lines, section.next_context, cursor, section.eof)
+        if find_result.new_index == -1:
+            ctx_text = "\n".join(section.next_context)
+            if section.eof:
+                raise ValueError(f"Invalid EOF Context {cursor}:\n{ctx_text}")
+            raise ValueError(f"Invalid Context {cursor}:\n{ctx_text}")
+
+        cursor = find_result.new_index + len(section.next_context)
+        parser.fuzz += find_result.fuzz
+        parser.index = section.end_index
+
+        for ch in section.section_chunks:
+            chunks.append(
+                Chunk(
+                    orig_index=ch.orig_index + find_result.new_index,
+                    del_lines=list(ch.del_lines),
+                    ins_lines=list(ch.ins_lines),
+                )
+            )
+
+    return ParsedUpdateDiff(chunks=chunks, fuzz=parser.fuzz)
+
+
+def _advance_cursor_to_anchor(
+    anchor: str,
+    input_lines: list[str],
+    cursor: int,
+    parser: ParserState,
+) -> int:
+    found = False
+
+    if not any(line == anchor for line in input_lines[:cursor]):
+        for i in range(cursor, len(input_lines)):
+            if input_lines[i] == anchor:
+                cursor = i + 1
+                found = True
+                break
+
+    if not found and not any(line.strip() == anchor.strip() for line in input_lines[:cursor]):
+        for i in range(cursor, len(input_lines)):
+            if input_lines[i].strip() == anchor.strip():
+                cursor = i + 1
+                parser.fuzz += 1
+                found = True
+                break
+
+    return cursor
+
+
+def _read_section(lines: list[str], start_index: int) -> ReadSectionResult:
+    context: list[str] = []
+    del_lines: list[str] = []
+    ins_lines: list[str] = []
+    section_chunks: list[Chunk] = []
+    mode: Literal["keep", "add", "delete"] = "keep"
+    index = start_index
+    orig_index = index
+
+    while index < len(lines):
+        raw = lines[index]
+        if (
+            raw.startswith("@@")
+            or raw.startswith(END_PATCH)
+            or raw.startswith("*** Update File:")
+            or raw.startswith("*** Delete File:")
+            or raw.startswith("*** Add File:")
+            or raw.startswith(END_FILE)
+        ):
+            break
+        if raw == "***":
+            break
+        if raw.startswith("***"):
+            raise ValueError(f"Invalid Line: {raw}")
+
+        index += 1
+        last_mode = mode
+        line = raw if raw else " "
+        prefix = line[0]
+        if prefix == "+":
+            mode = "add"
+        elif prefix == "-":
+            mode = "delete"
+        elif prefix == " ":
+            mode = "keep"
+        else:
+            raise ValueError(f"Invalid Line: {line}")
+
+        line_content = line[1:]
+        switching_to_context = mode == "keep" and last_mode != mode
+        if switching_to_context and (del_lines or ins_lines):
+            section_chunks.append(
+                Chunk(
+                    orig_index=len(context) - len(del_lines),
+                    del_lines=list(del_lines),
+                    ins_lines=list(ins_lines),
+                )
+            )
+            del_lines = []
+            ins_lines = []
+
+        if mode == "delete":
+            del_lines.append(line_content)
+            context.append(line_content)
+        elif mode == "add":
+            ins_lines.append(line_content)
+        else:
+            context.append(line_content)
+
+    if del_lines or ins_lines:
+        section_chunks.append(
+            Chunk(
+                orig_index=len(context) - len(del_lines),
+                del_lines=list(del_lines),
+                ins_lines=list(ins_lines),
+            )
+        )
+
+    if index < len(lines) and lines[index] == END_FILE:
+        return ReadSectionResult(context, section_chunks, index + 1, True)
+
+    if index == orig_index:
+        next_line = lines[index] if index < len(lines) else ""
+        raise ValueError(f"Nothing in this section - index={index} {next_line}")
+
+    return ReadSectionResult(context, section_chunks, index, False)
+
+
+@dataclass
+class ContextMatch:
+    new_index: int
+    fuzz: int
+
+
+def _find_context(lines: list[str], context: list[str], start: int, eof: bool) -> ContextMatch:
+    if eof:
+        end_start = max(0, len(lines) - len(context))
+        end_match = _find_context_core(lines, context, end_start)
+        if end_match.new_index != -1:
+            return end_match
+        fallback = _find_context_core(lines, context, start)
+        return ContextMatch(new_index=fallback.new_index, fuzz=fallback.fuzz + 10000)
+    return _find_context_core(lines, context, start)
+
+
+def _find_context_core(lines: list[str], context: list[str], start: int) -> ContextMatch:
+    if not context:
+        return ContextMatch(new_index=start, fuzz=0)
+
+    for i in range(start, len(lines)):
+        if _equals_slice(lines, context, i, lambda value: value):
+            return ContextMatch(new_index=i, fuzz=0)
+    for i in range(start, len(lines)):
+        if _equals_slice(lines, context, i, lambda value: value.rstrip()):
+            return ContextMatch(new_index=i, fuzz=1)
+    for i in range(start, len(lines)):
+        if _equals_slice(lines, context, i, lambda value: value.strip()):
+            return ContextMatch(new_index=i, fuzz=100)
+
+    return ContextMatch(new_index=-1, fuzz=0)
+
+
+def _equals_slice(
+    source: list[str], target: list[str], start: int, map_fn: Callable[[str], str]
+) -> bool:
+    if start + len(target) > len(source):
+        return False
+    for offset, target_value in enumerate(target):
+        if map_fn(source[start + offset]) != map_fn(target_value):
+            return False
+    return True
+
+
+def _apply_chunks(input: str, chunks: list[Chunk]) -> str:
+    orig_lines = input.split("\n")
+    dest_lines: list[str] = []
+    cursor = 0
+
+    for chunk in chunks:
+        if chunk.orig_index > len(orig_lines):
+            raise ValueError(
+                f"applyDiff: chunk.origIndex {chunk.orig_index} > input length {len(orig_lines)}"
+            )
+        if cursor > chunk.orig_index:
+            raise ValueError(
+                f"applyDiff: overlapping chunk at {chunk.orig_index} (cursor {cursor})"
+            )
+
+        dest_lines.extend(orig_lines[cursor : chunk.orig_index])
+        cursor = chunk.orig_index
+
+        if chunk.ins_lines:
+            dest_lines.extend(chunk.ins_lines)
+
+        cursor += len(chunk.del_lines)
+
+    dest_lines.extend(orig_lines[cursor:])
+    return "\n".join(dest_lines)
+
+
+__all__ = ["apply_diff"]

agents/editor.py

@@ -0,0 +1,47 @@
+from __future__ import annotations
+
+import sys
+from dataclasses import dataclass
+from typing import Literal, Protocol, runtime_checkable
+
+from .run_context import RunContextWrapper
+from .util._types import MaybeAwaitable
+
+ApplyPatchOperationType = Literal["create_file", "update_file", "delete_file"]
+
+_DATACLASS_KWARGS = {"slots": True} if sys.version_info >= (3, 10) else {}
+
+
+@dataclass(**_DATACLASS_KWARGS)
+class ApplyPatchOperation:
+    """Represents a single apply_patch editor operation requested by the model."""
+
+    type: ApplyPatchOperationType
+    path: str
+    diff: str | None = None
+    ctx_wrapper: RunContextWrapper | None = None
+
+
+@dataclass(**_DATACLASS_KWARGS)
+class ApplyPatchResult:
+    """Optional metadata returned by editor operations."""
+
+    status: Literal["completed", "failed"] | None = None
+    output: str | None = None
+
+
+@runtime_checkable
+class ApplyPatchEditor(Protocol):
+    """Host-defined editor that applies diffs on disk."""
+
+    def create_file(
+        self, operation: ApplyPatchOperation
+    ) -> MaybeAwaitable[ApplyPatchResult | str | None]: ...
+
+    def update_file(
+        self, operation: ApplyPatchOperation
+    ) -> MaybeAwaitable[ApplyPatchResult | str | None]: ...
+
+    def delete_file(
+        self, operation: ApplyPatchOperation
+    ) -> MaybeAwaitable[ApplyPatchResult | str | None]: ...

agents/exceptions.py

@@ -8,6 +8,11 @@ if TYPE_CHECKING:
     from .guardrail import InputGuardrailResult, OutputGuardrailResult
     from .items import ModelResponse, RunItem, TResponseInputItem
     from .run_context import RunContextWrapper
+    from .tool_guardrails import (
+        ToolGuardrailFunctionOutput,
+        ToolInputGuardrail,
+        ToolOutputGuardrail,
+    )
 
 from .util._pretty_print import pretty_print_run_error_details
 
@@ -94,3 +99,33 @@ class OutputGuardrailTripwireTriggered(AgentsException):
         super().__init__(
             f"Guardrail {guardrail_result.guardrail.__class__.__name__} triggered tripwire"
         )
+
+
+class ToolInputGuardrailTripwireTriggered(AgentsException):
+    """Exception raised when a tool input guardrail tripwire is triggered."""
+
+    guardrail: ToolInputGuardrail[Any]
+    """The guardrail that was triggered."""
+
+    output: ToolGuardrailFunctionOutput
+    """The output from the guardrail function."""
+
+    def __init__(self, guardrail: ToolInputGuardrail[Any], output: ToolGuardrailFunctionOutput):
+        self.guardrail = guardrail
+        self.output = output
+        super().__init__(f"Tool input guardrail {guardrail.__class__.__name__} triggered tripwire")
+
+
+class ToolOutputGuardrailTripwireTriggered(AgentsException):
+    """Exception raised when a tool output guardrail tripwire is triggered."""
+
+    guardrail: ToolOutputGuardrail[Any]
+    """The guardrail that was triggered."""
+
+    output: ToolGuardrailFunctionOutput
+    """The output from the guardrail function."""
+
+    def __init__(self, guardrail: ToolOutputGuardrail[Any], output: ToolGuardrailFunctionOutput):
+        self.guardrail = guardrail
+        self.output = output
+        super().__init__(f"Tool output guardrail {guardrail.__class__.__name__} triggered tripwire")

agents/extensions/experimental/__init__.py

@@ -0,0 +1,6 @@
+# This package contains experimental extensions to the agents package.
+# The interface and implementation details could be changed until being GAed.
+
+__all__ = [
+    "codex",
+]