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

agents/__init__.py

@@ -45,6 +45,8 @@ from .models.interface import Model, ModelProvider, ModelTracing
 from .models.openai_chatcompletions import OpenAIChatCompletionsModel
 from .models.openai_provider import OpenAIProvider
 from .models.openai_responses import OpenAIResponsesModel
+from .prompts import DynamicPromptFunction, GenerateDynamicPromptData, Prompt
+from .repl import run_demo_loop
 from .result import RunResult, RunResultStreaming
 from .run import RunConfig, Runner
 from .run_context import RunContextWrapper, TContext
@@ -102,6 +104,7 @@ from .tracing import (
     handoff_span,
     mcp_tools_span,
     set_trace_processors,
+    set_trace_provider,
     set_tracing_disabled,
     set_tracing_export_api_key,
     speech_group_span,
@@ -160,6 +163,7 @@ __all__ = [
     "ToolsToFinalOutputFunction",
     "ToolsToFinalOutputResult",
     "Runner",
+    "run_demo_loop",
     "Model",
     "ModelProvider",
     "ModelTracing",
@@ -176,6 +180,9 @@ __all__ = [
     "AgentsException",
     "InputGuardrailTripwireTriggered",
     "OutputGuardrailTripwireTriggered",
+    "DynamicPromptFunction",
+    "GenerateDynamicPromptData",
+    "Prompt",
     "MaxTurnsExceeded",
     "ModelBehaviorError",
     "UserError",
@@ -240,6 +247,7 @@ __all__ = [
     "guardrail_span",
     "handoff_span",
     "set_trace_processors",
+    "set_trace_provider",
     "set_tracing_disabled",
     "speech_group_span",
     "transcription_span",

agents/_run_impl.py

@@ -75,6 +75,7 @@ from .tool import (
     MCPToolApprovalRequest,
     Tool,
 )
+from .tool_context import ToolContext
 from .tracing import (
     SpanError,
     Trace,
@@ -543,23 +544,24 @@ class RunImpl:
             func_tool: FunctionTool, tool_call: ResponseFunctionToolCall
         ) -> Any:
             with function_span(func_tool.name) as span_fn:
+                tool_context = ToolContext.from_agent_context(context_wrapper, tool_call.call_id)
                 if config.trace_include_sensitive_data:
                     span_fn.span_data.input = tool_call.arguments
                 try:
                     _, _, result = await asyncio.gather(
-                        hooks.on_tool_start(context_wrapper, agent, func_tool),
+                        hooks.on_tool_start(tool_context, agent, func_tool),
                         (
-                            agent.hooks.on_tool_start(context_wrapper, agent, func_tool)
+                            agent.hooks.on_tool_start(tool_context, agent, func_tool)
                             if agent.hooks
                             else _coro.noop_coroutine()
                         ),
-                        func_tool.on_invoke_tool(context_wrapper, tool_call.arguments),
+                        func_tool.on_invoke_tool(tool_context, tool_call.arguments),
                     )
 
                     await asyncio.gather(
-                        hooks.on_tool_end(context_wrapper, agent, func_tool, result),
+                        hooks.on_tool_end(tool_context, agent, func_tool, result),
                         (
-                            agent.hooks.on_tool_end(context_wrapper, agent, func_tool, result)
+                            agent.hooks.on_tool_end(tool_context, agent, func_tool, result)
                             if agent.hooks
                             else _coro.noop_coroutine()
                         ),

agents/agent.py

@@ -7,6 +7,7 @@ from collections.abc import Awaitable
 from dataclasses import dataclass, field
 from typing import TYPE_CHECKING, Any, Callable, Generic, Literal, cast
 
+from openai.types.responses.response_prompt_param import ResponsePromptParam
 from typing_extensions import NotRequired, TypeAlias, TypedDict
 
 from .agent_output import AgentOutputSchemaBase
@@ -17,6 +18,7 @@ from .logger import logger
 from .mcp import MCPUtil
 from .model_settings import ModelSettings
 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 .util import _transforms
@@ -95,6 +97,12 @@ class Agent(Generic[TContext]):
     return a string.
     """
 
+    prompt: Prompt | DynamicPromptFunction | None = None
+    """A prompt object (or a function that returns a Prompt). Prompts allow you to dynamically
+    configure the instructions, tools and other config for an agent outside of your code. Only
+    usable with OpenAI models, using the Responses API.
+    """
+
     handoff_description: str | None = None
     """A description of the agent. This is used when the agent is used as a handoff, so that an
     LLM knows what it does and when to invoke it.
@@ -242,6 +250,12 @@ class Agent(Generic[TContext]):
 
         return None
 
+    async def get_prompt(
+        self, run_context: RunContextWrapper[TContext]
+    ) -> ResponsePromptParam | None:
+        """Get the prompt for the agent."""
+        return await PromptUtil.to_model_input(self.prompt, run_context, self)
+
     async def get_mcp_tools(self) -> list[Tool]:
         """Fetches the available tools from the MCP servers."""
         convert_schemas_to_strict = self.mcp_config.get("convert_schemas_to_strict", False)

agents/extensions/models/litellm_model.py

@@ -71,6 +71,7 @@ class LitellmModel(Model):
         handoffs: list[Handoff],
         tracing: ModelTracing,
         previous_response_id: str | None,
+        prompt: Any | None = None,
     ) -> ModelResponse:
         with generation_span(
             model=str(self.model),
@@ -88,6 +89,7 @@ class LitellmModel(Model):
                 span_generation,
                 tracing,
                 stream=False,
+                prompt=prompt,
             )
 
             assert isinstance(response.choices[0], litellm.types.utils.Choices)
@@ -153,8 +155,8 @@ class LitellmModel(Model):
         output_schema: AgentOutputSchemaBase | None,
         handoffs: list[Handoff],
         tracing: ModelTracing,
-        *,
         previous_response_id: str | None,
+        prompt: Any | None = None,
     ) -> AsyncIterator[TResponseStreamEvent]:
         with generation_span(
             model=str(self.model),
@@ -172,6 +174,7 @@ class LitellmModel(Model):
                 span_generation,
                 tracing,
                 stream=True,
+                prompt=prompt,
             )
 
             final_response: Response | None = None
@@ -202,6 +205,7 @@ class LitellmModel(Model):
         span: Span[GenerationSpanData],
         tracing: ModelTracing,
         stream: Literal[True],
+        prompt: Any | None = None,
     ) -> tuple[Response, AsyncStream[ChatCompletionChunk]]: ...
 
     @overload
@@ -216,6 +220,7 @@ class LitellmModel(Model):
         span: Span[GenerationSpanData],
         tracing: ModelTracing,
         stream: Literal[False],
+        prompt: Any | None = None,
     ) -> litellm.types.utils.ModelResponse: ...
 
     async def _fetch_response(
@@ -229,6 +234,7 @@ class LitellmModel(Model):
         span: Span[GenerationSpanData],
         tracing: ModelTracing,
         stream: bool = False,
+        prompt: Any | None = None,
     ) -> litellm.types.utils.ModelResponse | tuple[Response, AsyncStream[ChatCompletionChunk]]:
         converted_messages = Converter.items_to_messages(input)
 
@@ -284,6 +290,10 @@ class LitellmModel(Model):
         if model_settings.extra_body and isinstance(model_settings.extra_body, dict):
             extra_kwargs.update(model_settings.extra_body)
 
+        # Add kwargs from model_settings.extra_args, filtering out None values
+        if model_settings.extra_args:
+            extra_kwargs.update(model_settings.extra_args)
+
         ret = await litellm.acompletion(
             model=self.model,
             messages=converted_messages,

agents/function_schema.py

@@ -13,6 +13,7 @@ from pydantic import BaseModel, Field, create_model
 from .exceptions import UserError
 from .run_context import RunContextWrapper
 from .strict_schema import ensure_strict_json_schema
+from .tool_context import ToolContext
 
 
 @dataclass
@@ -222,7 +223,8 @@ def function_schema(
         doc_info = None
         param_descs = {}
 
-    func_name = name_override or doc_info.name if doc_info else func.__name__
+    # Ensure name_override takes precedence even if docstring info is disabled.
+    func_name = name_override or (doc_info.name if doc_info else func.__name__)
 
     # 2. Inspect function signature and get type hints
     sig = inspect.signature(func)
@@ -237,21 +239,21 @@ def function_schema(
         ann = type_hints.get(first_name, first_param.annotation)
         if ann != inspect._empty:
             origin = get_origin(ann) or ann
-            if origin is RunContextWrapper:
+            if origin is RunContextWrapper or origin is ToolContext:
                 takes_context = True  # Mark that the function takes context
             else:
                 filtered_params.append((first_name, first_param))
         else:
             filtered_params.append((first_name, first_param))
 
-    # For parameters other than the first, raise error if any use RunContextWrapper.
+    # For parameters other than the first, raise error if any use RunContextWrapper or ToolContext.
     for name, param in params[1:]:
         ann = type_hints.get(name, param.annotation)
         if ann != inspect._empty:
             origin = get_origin(ann) or ann
-            if origin is RunContextWrapper:
+            if origin is RunContextWrapper or origin is ToolContext:
                 raise UserError(
-                    f"RunContextWrapper param found at non-first position in function"
+                    f"RunContextWrapper/ToolContext param found at non-first position in function"
                     f" {func.__name__}"
                 )
         filtered_params.append((name, param))

agents/handoffs.py

@@ -1,6 +1,7 @@
 from __future__ import annotations
 
 import inspect
+import json
 from collections.abc import Awaitable
 from dataclasses import dataclass
 from typing import TYPE_CHECKING, Any, Callable, Generic, cast, overload
@@ -99,8 +100,7 @@ class Handoff(Generic[TContext]):
     """
 
     def get_transfer_message(self, agent: Agent[Any]) -> str:
-        base = f"{{'assistant': '{agent.name}'}}"
-        return base
+        return json.dumps({"assistant": agent.name})
 
     @classmethod
     def default_tool_name(cls, agent: Agent[Any]) -> str:

agents/mcp/server.py

@@ -340,10 +340,10 @@ class MCPServerStreamableHttpParams(TypedDict):
     headers: NotRequired[dict[str, str]]
     """The headers to send to the server."""
 
-    timeout: NotRequired[timedelta]
+    timeout: NotRequired[timedelta | float]
     """The timeout for the HTTP request. Defaults to 5 seconds."""
 
-    sse_read_timeout: NotRequired[timedelta]
+    sse_read_timeout: NotRequired[timedelta | float]
     """The timeout for the SSE connection, in seconds. Defaults to 5 minutes."""
 
     terminate_on_close: NotRequired[bool]
@@ -401,8 +401,8 @@ class MCPServerStreamableHttp(_MCPServerWithClientSession):
         return streamablehttp_client(
             url=self.params["url"],
             headers=self.params.get("headers", None),
-            timeout=self.params.get("timeout", timedelta(seconds=30)),
-            sse_read_timeout=self.params.get("sse_read_timeout", timedelta(seconds=60 * 5)),
+            timeout=self.params.get("timeout", 5),
+            sse_read_timeout=self.params.get("sse_read_timeout", 60 * 5),
             terminate_on_close=self.params.get("terminate_on_close", True),
         )
 

agents/model_settings.py

@@ -73,6 +73,11 @@ class ModelSettings:
     """Additional headers to provide with the request.
     Defaults to None if not provided."""
 
+    extra_args: dict[str, Any] | None = None
+    """Arbitrary keyword arguments to pass to the model API call.
+    These will be passed directly to the underlying model provider's API.
+    Use with caution as not all models support all parameters."""
+
     def resolve(self, override: ModelSettings | None) -> ModelSettings:
         """Produce a new ModelSettings by overlaying any non-None values from the
         override on top of this instance."""
@@ -84,6 +89,16 @@ class ModelSettings:
             for field in fields(self)
             if getattr(override, field.name) is not None
         }
+
+        # Handle extra_args merging specially - merge dictionaries instead of replacing
+        if self.extra_args is not None or override.extra_args is not None:
+            merged_args = {}
+            if self.extra_args:
+                merged_args.update(self.extra_args)
+            if override.extra_args:
+                merged_args.update(override.extra_args)
+            changes["extra_args"] = merged_args if merged_args else None
+
         return replace(self, **changes)
 
     def to_json_dict(self) -> dict[str, Any]:

agents/models/interface.py

@@ -5,6 +5,8 @@ import enum
 from collections.abc import AsyncIterator
 from typing import TYPE_CHECKING
 
+from openai.types.responses.response_prompt_param import ResponsePromptParam
+
 from ..agent_output import AgentOutputSchemaBase
 from ..handoffs import Handoff
 from ..items import ModelResponse, TResponseInputItem, TResponseStreamEvent
@@ -46,6 +48,7 @@ class Model(abc.ABC):
         tracing: ModelTracing,
         *,
         previous_response_id: str | None,
+        prompt: ResponsePromptParam | None,
     ) -> ModelResponse:
         """Get a response from the model.
 
@@ -59,6 +62,7 @@ class Model(abc.ABC):
             tracing: Tracing configuration.
             previous_response_id: the ID of the previous response. Generally not used by the model,
                 except for the OpenAI Responses API.
+            prompt: The prompt config to use for the model.
 
         Returns:
             The full model response.
@@ -77,6 +81,7 @@ class Model(abc.ABC):
         tracing: ModelTracing,
         *,
         previous_response_id: str | None,
+        prompt: ResponsePromptParam | None,
     ) -> AsyncIterator[TResponseStreamEvent]:
         """Stream a response from the model.
 
@@ -90,6 +95,7 @@ class Model(abc.ABC):
             tracing: Tracing configuration.
             previous_response_id: the ID of the previous response. Generally not used by the model,
                 except for the OpenAI Responses API.
+            prompt: The prompt config to use for the model.
 
         Returns:
             An iterator of response stream events, in OpenAI Responses format.

agents/models/openai_chatcompletions.py

@@ -9,6 +9,7 @@ from openai import NOT_GIVEN, AsyncOpenAI, AsyncStream
 from openai.types import ChatModel
 from openai.types.chat import ChatCompletion, ChatCompletionChunk
 from openai.types.responses import Response
+from openai.types.responses.response_prompt_param import ResponsePromptParam
 from openai.types.responses.response_usage import InputTokensDetails, OutputTokensDetails
 
 from .. import _debug
@@ -53,6 +54,7 @@ class OpenAIChatCompletionsModel(Model):
         handoffs: list[Handoff],
         tracing: ModelTracing,
         previous_response_id: str | None,
+        prompt: ResponsePromptParam | None = None,
     ) -> ModelResponse:
         with generation_span(
             model=str(self.model),
@@ -69,6 +71,7 @@ class OpenAIChatCompletionsModel(Model):
                 span_generation,
                 tracing,
                 stream=False,
+                prompt=prompt,
             )
 
             first_choice = response.choices[0]
@@ -136,8 +139,8 @@ class OpenAIChatCompletionsModel(Model):
         output_schema: AgentOutputSchemaBase | None,
         handoffs: list[Handoff],
         tracing: ModelTracing,
-        *,
         previous_response_id: str | None,
+        prompt: ResponsePromptParam | None = None,
     ) -> AsyncIterator[TResponseStreamEvent]:
         """
         Yields a partial message as it is generated, as well as the usage information.
@@ -157,6 +160,7 @@ class OpenAIChatCompletionsModel(Model):
                 span_generation,
                 tracing,
                 stream=True,
+                prompt=prompt,
             )
 
             final_response: Response | None = None
@@ -187,6 +191,7 @@ class OpenAIChatCompletionsModel(Model):
         span: Span[GenerationSpanData],
         tracing: ModelTracing,
         stream: Literal[True],
+        prompt: ResponsePromptParam | None = None,
     ) -> tuple[Response, AsyncStream[ChatCompletionChunk]]: ...
 
     @overload
@@ -201,6 +206,7 @@ class OpenAIChatCompletionsModel(Model):
         span: Span[GenerationSpanData],
         tracing: ModelTracing,
         stream: Literal[False],
+        prompt: ResponsePromptParam | None = None,
     ) -> ChatCompletion: ...
 
     async def _fetch_response(
@@ -214,6 +220,7 @@ class OpenAIChatCompletionsModel(Model):
         span: Span[GenerationSpanData],
         tracing: ModelTracing,
         stream: bool = False,
+        prompt: ResponsePromptParam | None = None,
     ) -> ChatCompletion | tuple[Response, AsyncStream[ChatCompletionChunk]]:
         converted_messages = Converter.items_to_messages(input)
 
@@ -281,6 +288,7 @@ class OpenAIChatCompletionsModel(Model):
             extra_query=model_settings.extra_query,
             extra_body=model_settings.extra_body,
             metadata=self._non_null_or_not_given(model_settings.metadata),
+            **(model_settings.extra_args or {}),
         )
 
         if isinstance(ret, ChatCompletion):

agents/models/openai_responses.py

@@ -17,6 +17,7 @@ from openai.types.responses import (
     WebSearchToolParam,
     response_create_params,
 )
+from openai.types.responses.response_prompt_param import ResponsePromptParam
 
 from .. import _debug
 from ..agent_output import AgentOutputSchemaBase
@@ -74,6 +75,7 @@ class OpenAIResponsesModel(Model):
         handoffs: list[Handoff],
         tracing: ModelTracing,
         previous_response_id: str | None,
+        prompt: ResponsePromptParam | None = None,
     ) -> ModelResponse:
         with response_span(disabled=tracing.is_disabled()) as span_response:
             try:
@@ -86,6 +88,7 @@ class OpenAIResponsesModel(Model):
                     handoffs,
                     previous_response_id,
                     stream=False,
+                    prompt=prompt,
                 )
 
                 if _debug.DONT_LOG_MODEL_DATA:
@@ -141,6 +144,7 @@ class OpenAIResponsesModel(Model):
         handoffs: list[Handoff],
         tracing: ModelTracing,
         previous_response_id: str | None,
+        prompt: ResponsePromptParam | None = None,
     ) -> AsyncIterator[ResponseStreamEvent]:
         """
         Yields a partial message as it is generated, as well as the usage information.
@@ -156,6 +160,7 @@ class OpenAIResponsesModel(Model):
                     handoffs,
                     previous_response_id,
                     stream=True,
+                    prompt=prompt,
                 )
 
                 final_response: Response | None = None
@@ -192,6 +197,7 @@ class OpenAIResponsesModel(Model):
         handoffs: list[Handoff],
         previous_response_id: str | None,
         stream: Literal[True],
+        prompt: ResponsePromptParam | None = None,
     ) -> AsyncStream[ResponseStreamEvent]: ...
 
     @overload
@@ -205,6 +211,7 @@ class OpenAIResponsesModel(Model):
         handoffs: list[Handoff],
         previous_response_id: str | None,
         stream: Literal[False],
+        prompt: ResponsePromptParam | None = None,
     ) -> Response: ...
 
     async def _fetch_response(
@@ -217,6 +224,7 @@ class OpenAIResponsesModel(Model):
         handoffs: list[Handoff],
         previous_response_id: str | None,
         stream: Literal[True] | Literal[False] = False,
+        prompt: ResponsePromptParam | None = None,
     ) -> Response | AsyncStream[ResponseStreamEvent]:
         list_input = ItemHelpers.input_to_new_input_list(input)
 
@@ -252,6 +260,7 @@ class OpenAIResponsesModel(Model):
             input=list_input,
             include=converted_tools.includes,
             tools=converted_tools.tools,
+            prompt=self._non_null_or_not_given(prompt),
             temperature=self._non_null_or_not_given(model_settings.temperature),
             top_p=self._non_null_or_not_given(model_settings.top_p),
             truncation=self._non_null_or_not_given(model_settings.truncation),
@@ -266,6 +275,7 @@ class OpenAIResponsesModel(Model):
             store=self._non_null_or_not_given(model_settings.store),
             reasoning=self._non_null_or_not_given(model_settings.reasoning),
             metadata=self._non_null_or_not_given(model_settings.metadata),
+            **(model_settings.extra_args or {}),
         )
 
     def _get_client(self) -> AsyncOpenAI:

agents/prompts.py

@@ -0,0 +1,76 @@
+from __future__ import annotations
+
+import inspect
+from dataclasses import dataclass
+from typing import TYPE_CHECKING, Any, Callable
+
+from openai.types.responses.response_prompt_param import (
+    ResponsePromptParam,
+    Variables as ResponsesPromptVariables,
+)
+from typing_extensions import NotRequired, TypedDict
+
+from agents.util._types import MaybeAwaitable
+
+from .exceptions import UserError
+from .run_context import RunContextWrapper
+
+if TYPE_CHECKING:
+    from .agent import Agent
+
+
+class Prompt(TypedDict):
+    """Prompt configuration to use for interacting with an OpenAI model."""
+
+    id: str
+    """The unique ID of the prompt."""
+
+    version: NotRequired[str]
+    """Optional version of the prompt."""
+
+    variables: NotRequired[dict[str, ResponsesPromptVariables]]
+    """Optional variables to substitute into the prompt."""
+
+
+@dataclass
+class GenerateDynamicPromptData:
+    """Inputs to a function that allows you to dynamically generate a prompt."""
+
+    context: RunContextWrapper[Any]
+    """The run context."""
+
+    agent: Agent[Any]
+    """The agent for which the prompt is being generated."""
+
+
+DynamicPromptFunction = Callable[[GenerateDynamicPromptData], MaybeAwaitable[Prompt]]
+"""A function that dynamically generates a prompt."""
+
+
+class PromptUtil:
+    @staticmethod
+    async def to_model_input(
+        prompt: Prompt | DynamicPromptFunction | None,
+        context: RunContextWrapper[Any],
+        agent: Agent[Any],
+    ) -> ResponsePromptParam | None:
+        if prompt is None:
+            return None
+
+        resolved_prompt: Prompt
+        if isinstance(prompt, dict):
+            resolved_prompt = prompt
+        else:
+            func_result = prompt(GenerateDynamicPromptData(context=context, agent=agent))
+            if inspect.isawaitable(func_result):
+                resolved_prompt = await func_result
+            else:
+                resolved_prompt = func_result
+            if not isinstance(resolved_prompt, dict):
+                raise UserError("Dynamic prompt function must return a Prompt")
+
+        return {
+            "id": resolved_prompt["id"],
+            "version": resolved_prompt.get("version"),
+            "variables": resolved_prompt.get("variables"),
+        }

agents/repl.py

@@ -0,0 +1,65 @@
+from __future__ import annotations
+
+from typing import Any
+
+from openai.types.responses.response_text_delta_event import ResponseTextDeltaEvent
+
+from .agent import Agent
+from .items import ItemHelpers, TResponseInputItem
+from .result import RunResultBase
+from .run import Runner
+from .stream_events import AgentUpdatedStreamEvent, RawResponsesStreamEvent, RunItemStreamEvent
+
+
+async def run_demo_loop(agent: Agent[Any], *, stream: bool = True) -> None:
+    """Run a simple REPL loop with the given agent.
+
+    This utility allows quick manual testing and debugging of an agent from the
+    command line. Conversation state is preserved across turns. Enter ``exit``
+    or ``quit`` to stop the loop.
+
+    Args:
+        agent: The starting agent to run.
+        stream: Whether to stream the agent output.
+    """
+
+    current_agent = agent
+    input_items: list[TResponseInputItem] = []
+    while True:
+        try:
+            user_input = input(" > ")
+        except (EOFError, KeyboardInterrupt):
+            print()
+            break
+        if user_input.strip().lower() in {"exit", "quit"}:
+            break
+        if not user_input:
+            continue
+
+        input_items.append({"role": "user", "content": user_input})
+
+        result: RunResultBase
+        if stream:
+            result = Runner.run_streamed(current_agent, input=input_items)
+            async for event in result.stream_events():
+                if isinstance(event, RawResponsesStreamEvent):
+                    if isinstance(event.data, ResponseTextDeltaEvent):
+                        print(event.data.delta, end="", flush=True)
+                elif isinstance(event, RunItemStreamEvent):
+                    if event.item.type == "tool_call_item":
+                        print("\n[tool called]", flush=True)
+                    elif event.item.type == "tool_call_output_item":
+                        print(f"\n[tool output: {event.item.output}]", flush=True)
+                    elif event.item.type == "message_output_item":
+                        message = ItemHelpers.text_message_output(event.item)
+                        print(message, end="", flush=True)
+                elif isinstance(event, AgentUpdatedStreamEvent):
+                    print(f"\n[Agent updated: {event.new_agent.name}]", flush=True)
+            print()
+        else:
+            result = await Runner.run(current_agent, input_items)
+            if result.final_output is not None:
+                print(result.final_output)
+
+        current_agent = result.last_agent
+        input_items = result.to_input_list()