openai-agents 0.0.6__py3-none-any.whl → 0.0.8__py3-none-any.whl

agents/mcp/server.py

@@ -0,0 +1,301 @@
+from __future__ import annotations
+
+import abc
+import asyncio
+from contextlib import AbstractAsyncContextManager, AsyncExitStack
+from pathlib import Path
+from typing import Any, Literal
+
+from anyio.streams.memory import MemoryObjectReceiveStream, MemoryObjectSendStream
+from mcp import ClientSession, StdioServerParameters, Tool as MCPTool, stdio_client
+from mcp.client.sse import sse_client
+from mcp.types import CallToolResult, JSONRPCMessage
+from typing_extensions import NotRequired, TypedDict
+
+from ..exceptions import UserError
+from ..logger import logger
+
+
+class MCPServer(abc.ABC):
+    """Base class for Model Context Protocol servers."""
+
+    @abc.abstractmethod
+    async def connect(self):
+        """Connect to the server. For example, this might mean spawning a subprocess or
+        opening a network connection. The server is expected to remain connected until
+        `cleanup()` is called.
+        """
+        pass
+
+    @property
+    @abc.abstractmethod
+    def name(self) -> str:
+        """A readable name for the server."""
+        pass
+
+    @abc.abstractmethod
+    async def cleanup(self):
+        """Cleanup the server. For example, this might mean closing a subprocess or
+        closing a network connection.
+        """
+        pass
+
+    @abc.abstractmethod
+    async def list_tools(self) -> list[MCPTool]:
+        """List the tools available on the server."""
+        pass
+
+    @abc.abstractmethod
+    async def call_tool(self, tool_name: str, arguments: dict[str, Any] | None) -> CallToolResult:
+        """Invoke a tool on the server."""
+        pass
+
+
+class _MCPServerWithClientSession(MCPServer, abc.ABC):
+    """Base class for MCP servers that use a `ClientSession` to communicate with the server."""
+
+    def __init__(self, cache_tools_list: bool):
+        """
+        Args:
+            cache_tools_list: Whether to cache the tools list. If `True`, the tools list will be
+            cached and only fetched from the server once. If `False`, the tools list will be
+            fetched from the server on each call to `list_tools()`. The cache can be invalidated
+            by calling `invalidate_tools_cache()`. You should set this to `True` if you know the
+            server will not change its tools list, because it can drastically improve latency
+            (by avoiding a round-trip to the server every time).
+        """
+        self.session: ClientSession | None = None
+        self.exit_stack: AsyncExitStack = AsyncExitStack()
+        self._cleanup_lock: asyncio.Lock = asyncio.Lock()
+        self.cache_tools_list = cache_tools_list
+
+        # The cache is always dirty at startup, so that we fetch tools at least once
+        self._cache_dirty = True
+        self._tools_list: list[MCPTool] | None = None
+
+    @abc.abstractmethod
+    def create_streams(
+        self,
+    ) -> AbstractAsyncContextManager[
+        tuple[
+            MemoryObjectReceiveStream[JSONRPCMessage | Exception],
+            MemoryObjectSendStream[JSONRPCMessage],
+        ]
+    ]:
+        """Create the streams for the server."""
+        pass
+
+    async def __aenter__(self):
+        await self.connect()
+        return self
+
+    async def __aexit__(self, exc_type, exc_value, traceback):
+        await self.cleanup()
+
+    def invalidate_tools_cache(self):
+        """Invalidate the tools cache."""
+        self._cache_dirty = True
+
+    async def connect(self):
+        """Connect to the server."""
+        try:
+            transport = await self.exit_stack.enter_async_context(self.create_streams())
+            read, write = transport
+            session = await self.exit_stack.enter_async_context(ClientSession(read, write))
+            await session.initialize()
+            self.session = session
+        except Exception as e:
+            logger.error(f"Error initializing MCP server: {e}")
+            await self.cleanup()
+            raise
+
+    async def list_tools(self) -> list[MCPTool]:
+        """List the tools available on the server."""
+        if not self.session:
+            raise UserError("Server not initialized. Make sure you call `connect()` first.")
+
+        # Return from cache if caching is enabled, we have tools, and the cache is not dirty
+        if self.cache_tools_list and not self._cache_dirty and self._tools_list:
+            return self._tools_list
+
+        # Reset the cache dirty to False
+        self._cache_dirty = False
+
+        # Fetch the tools from the server
+        self._tools_list = (await self.session.list_tools()).tools
+        return self._tools_list
+
+    async def call_tool(self, tool_name: str, arguments: dict[str, Any] | None) -> CallToolResult:
+        """Invoke a tool on the server."""
+        if not self.session:
+            raise UserError("Server not initialized. Make sure you call `connect()` first.")
+
+        return await self.session.call_tool(tool_name, arguments)
+
+    async def cleanup(self):
+        """Cleanup the server."""
+        async with self._cleanup_lock:
+            try:
+                await self.exit_stack.aclose()
+                self.session = None
+            except Exception as e:
+                logger.error(f"Error cleaning up server: {e}")
+
+
+class MCPServerStdioParams(TypedDict):
+    """Mirrors `mcp.client.stdio.StdioServerParameters`, but lets you pass params without another
+    import.
+    """
+
+    command: str
+    """The executable to run to start the server. For example, `python` or `node`."""
+
+    args: NotRequired[list[str]]
+    """Command line args to pass to the `command` executable. For example, `['foo.py']` or
+    `['server.js', '--port', '8080']`."""
+
+    env: NotRequired[dict[str, str]]
+    """The environment variables to set for the server. ."""
+
+    cwd: NotRequired[str | Path]
+    """The working directory to use when spawning the process."""
+
+    encoding: NotRequired[str]
+    """The text encoding used when sending/receiving messages to the server. Defaults to `utf-8`."""
+
+    encoding_error_handler: NotRequired[Literal["strict", "ignore", "replace"]]
+    """The text encoding error handler. Defaults to `strict`.
+
+    See https://docs.python.org/3/library/codecs.html#codec-base-classes for
+    explanations of possible values.
+    """
+
+
+class MCPServerStdio(_MCPServerWithClientSession):
+    """MCP server implementation that uses the stdio transport. See the [spec]
+    (https://spec.modelcontextprotocol.io/specification/2024-11-05/basic/transports/#stdio) for
+    details.
+    """
+
+    def __init__(
+        self,
+        params: MCPServerStdioParams,
+        cache_tools_list: bool = False,
+        name: str | None = None,
+    ):
+        """Create a new MCP server based on the stdio transport.
+
+        Args:
+            params: The params that configure the server. This includes the command to run to
+                start the server, the args to pass to the command, the environment variables to
+                set for the server, the working directory to use when spawning the process, and
+                the text encoding used when sending/receiving messages to the server.
+            cache_tools_list: Whether to cache the tools list. If `True`, the tools list will be
+                cached and only fetched from the server once. If `False`, the tools list will be
+                fetched from the server on each call to `list_tools()`. The cache can be
+                invalidated by calling `invalidate_tools_cache()`. You should set this to `True`
+                if you know the server will not change its tools list, because it can drastically
+                improve latency (by avoiding a round-trip to the server every time).
+            name: A readable name for the server. If not provided, we'll create one from the
+                command.
+        """
+        super().__init__(cache_tools_list)
+
+        self.params = StdioServerParameters(
+            command=params["command"],
+            args=params.get("args", []),
+            env=params.get("env"),
+            cwd=params.get("cwd"),
+            encoding=params.get("encoding", "utf-8"),
+            encoding_error_handler=params.get("encoding_error_handler", "strict"),
+        )
+
+        self._name = name or f"stdio: {self.params.command}"
+
+    def create_streams(
+        self,
+    ) -> AbstractAsyncContextManager[
+        tuple[
+            MemoryObjectReceiveStream[JSONRPCMessage | Exception],
+            MemoryObjectSendStream[JSONRPCMessage],
+        ]
+    ]:
+        """Create the streams for the server."""
+        return stdio_client(self.params)
+
+    @property
+    def name(self) -> str:
+        """A readable name for the server."""
+        return self._name
+
+
+class MCPServerSseParams(TypedDict):
+    """Mirrors the params in`mcp.client.sse.sse_client`."""
+
+    url: str
+    """The URL of the server."""
+
+    headers: NotRequired[dict[str, str]]
+    """The headers to send to the server."""
+
+    timeout: NotRequired[float]
+    """The timeout for the HTTP request. Defaults to 5 seconds."""
+
+    sse_read_timeout: NotRequired[float]
+    """The timeout for the SSE connection, in seconds. Defaults to 5 minutes."""
+
+
+class MCPServerSse(_MCPServerWithClientSession):
+    """MCP server implementation that uses the HTTP with SSE transport. See the [spec]
+    (https://spec.modelcontextprotocol.io/specification/2024-11-05/basic/transports/#http-with-sse)
+    for details.
+    """
+
+    def __init__(
+        self,
+        params: MCPServerSseParams,
+        cache_tools_list: bool = False,
+        name: str | None = None,
+    ):
+        """Create a new MCP server based on the HTTP with SSE transport.
+
+        Args:
+            params: The params that configure the server. This includes the URL of the server,
+                the headers to send to the server, the timeout for the HTTP request, and the
+                timeout for the SSE connection.
+
+            cache_tools_list: Whether to cache the tools list. If `True`, the tools list will be
+                cached and only fetched from the server once. If `False`, the tools list will be
+                fetched from the server on each call to `list_tools()`. The cache can be
+                invalidated by calling `invalidate_tools_cache()`. You should set this to `True`
+                if you know the server will not change its tools list, because it can drastically
+                improve latency (by avoiding a round-trip to the server every time).
+
+            name: A readable name for the server. If not provided, we'll create one from the
+                URL.
+        """
+        super().__init__(cache_tools_list)
+
+        self.params = params
+        self._name = name or f"sse: {self.params['url']}"
+
+    def create_streams(
+        self,
+    ) -> AbstractAsyncContextManager[
+        tuple[
+            MemoryObjectReceiveStream[JSONRPCMessage | Exception],
+            MemoryObjectSendStream[JSONRPCMessage],
+        ]
+    ]:
+        """Create the streams for the server."""
+        return sse_client(
+            url=self.params["url"],
+            headers=self.params.get("headers", None),
+            timeout=self.params.get("timeout", 5),
+            sse_read_timeout=self.params.get("sse_read_timeout", 60 * 5),
+        )
+
+    @property
+    def name(self) -> str:
+        """A readable name for the server."""
+        return self._name

agents/mcp/util.py

@@ -0,0 +1,131 @@
+import functools
+import json
+from typing import TYPE_CHECKING, Any
+
+from agents.strict_schema import ensure_strict_json_schema
+
+from .. import _debug
+from ..exceptions import AgentsException, ModelBehaviorError, UserError
+from ..logger import logger
+from ..run_context import RunContextWrapper
+from ..tool import FunctionTool, Tool
+from ..tracing import FunctionSpanData, get_current_span, mcp_tools_span
+
+if TYPE_CHECKING:
+    from mcp.types import Tool as MCPTool
+
+    from .server import MCPServer
+
+
+class MCPUtil:
+    """Set of utilities for interop between MCP and Agents SDK tools."""
+
+    @classmethod
+    async def get_all_function_tools(
+        cls, servers: list["MCPServer"], convert_schemas_to_strict: bool
+    ) -> list[Tool]:
+        """Get all function tools from a list of MCP servers."""
+        tools = []
+        tool_names: set[str] = set()
+        for server in servers:
+            server_tools = await cls.get_function_tools(server, convert_schemas_to_strict)
+            server_tool_names = {tool.name for tool in server_tools}
+            if len(server_tool_names & tool_names) > 0:
+                raise UserError(
+                    f"Duplicate tool names found across MCP servers: "
+                    f"{server_tool_names & tool_names}"
+                )
+            tool_names.update(server_tool_names)
+            tools.extend(server_tools)
+
+        return tools
+
+    @classmethod
+    async def get_function_tools(
+        cls, server: "MCPServer", convert_schemas_to_strict: bool
+    ) -> list[Tool]:
+        """Get all function tools from a single MCP server."""
+
+        with mcp_tools_span(server=server.name) as span:
+            tools = await server.list_tools()
+            span.span_data.result = [tool.name for tool in tools]
+
+        return [cls.to_function_tool(tool, server, convert_schemas_to_strict) for tool in tools]
+
+    @classmethod
+    def to_function_tool(
+        cls, tool: "MCPTool", server: "MCPServer", convert_schemas_to_strict: bool
+    ) -> FunctionTool:
+        """Convert an MCP tool to an Agents SDK function tool."""
+        invoke_func = functools.partial(cls.invoke_mcp_tool, server, tool)
+        schema, is_strict = tool.inputSchema, False
+        if convert_schemas_to_strict:
+            try:
+                schema = ensure_strict_json_schema(schema)
+                is_strict = True
+            except Exception as e:
+                logger.info(f"Error converting MCP schema to strict mode: {e}")
+
+        return FunctionTool(
+            name=tool.name,
+            description=tool.description or "",
+            params_json_schema=schema,
+            on_invoke_tool=invoke_func,
+            strict_json_schema=is_strict,
+        )
+
+    @classmethod
+    async def invoke_mcp_tool(
+        cls, server: "MCPServer", tool: "MCPTool", context: RunContextWrapper[Any], input_json: str
+    ) -> str:
+        """Invoke an MCP tool and return the result as a string."""
+        try:
+            json_data: dict[str, Any] = json.loads(input_json) if input_json else {}
+        except Exception as e:
+            if _debug.DONT_LOG_TOOL_DATA:
+                logger.debug(f"Invalid JSON input for tool {tool.name}")
+            else:
+                logger.debug(f"Invalid JSON input for tool {tool.name}: {input_json}")
+            raise ModelBehaviorError(
+                f"Invalid JSON input for tool {tool.name}: {input_json}"
+            ) from e
+
+        if _debug.DONT_LOG_TOOL_DATA:
+            logger.debug(f"Invoking MCP tool {tool.name}")
+        else:
+            logger.debug(f"Invoking MCP tool {tool.name} with input {input_json}")
+
+        try:
+            result = await server.call_tool(tool.name, json_data)
+        except Exception as e:
+            logger.error(f"Error invoking MCP tool {tool.name}: {e}")
+            raise AgentsException(f"Error invoking MCP tool {tool.name}: {e}") from e
+
+        if _debug.DONT_LOG_TOOL_DATA:
+            logger.debug(f"MCP tool {tool.name} completed.")
+        else:
+            logger.debug(f"MCP tool {tool.name} returned {result}")
+
+        # The MCP tool result is a list of content items, whereas OpenAI tool outputs are a single
+        # string. We'll try to convert.
+        if len(result.content) == 1:
+            tool_output = result.content[0].model_dump_json()
+        elif len(result.content) > 1:
+            tool_output = json.dumps([item.model_dump() for item in result.content])
+        else:
+            logger.error(f"Errored MCP tool result: {result}")
+            tool_output = "Error running tool."
+
+        current_span = get_current_span()
+        if current_span:
+            if isinstance(current_span.span_data, FunctionSpanData):
+                current_span.span_data.output = tool_output
+                current_span.span_data.mcp_data = {
+                    "server": server.name,
+                }
+            else:
+                logger.warning(
+                    f"Current span is not a FunctionSpanData, skipping tool output: {current_span}"
+                )
+
+        return tool_output

agents/model_settings.py

@@ -1,8 +1,10 @@
 from __future__ import annotations
 
-from dataclasses import dataclass
+from dataclasses import dataclass, fields, replace
 from typing import Literal
 
+from openai.types.shared import Reasoning
+
 
 @dataclass
 class ModelSettings:
@@ -30,8 +32,9 @@ class ModelSettings:
     tool_choice: Literal["auto", "required", "none"] | str | None = None
     """The tool choice to use when calling the model."""
 
-    parallel_tool_calls: bool | None = False
-    """Whether to use parallel tool calls when calling the model."""
+    parallel_tool_calls: bool | None = None
+    """Whether to use parallel tool calls when calling the model.
+    Defaults to False if not provided."""
 
     truncation: Literal["auto", "disabled"] | None = None
     """The truncation strategy to use when calling the model."""
@@ -39,18 +42,27 @@ class ModelSettings:
     max_tokens: int | None = None
     """The maximum number of output tokens to generate."""
 
+    reasoning: Reasoning | None = None
+    """Configuration options for
+    [reasoning models](https://platform.openai.com/docs/guides/reasoning).
+    """
+
+    metadata: dict[str, str] | None = None
+    """Metadata to include with the model response call."""
+
+    store: bool | None = None
+    """Whether to store the generated model response for later retrieval.
+    Defaults to True if not provided."""
+
     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."""
         if override is None:
             return self
-        return ModelSettings(
-            temperature=override.temperature or self.temperature,
-            top_p=override.top_p or self.top_p,
-            frequency_penalty=override.frequency_penalty or self.frequency_penalty,
-            presence_penalty=override.presence_penalty or self.presence_penalty,
-            tool_choice=override.tool_choice or self.tool_choice,
-            parallel_tool_calls=override.parallel_tool_calls or self.parallel_tool_calls,
-            truncation=override.truncation or self.truncation,
-            max_tokens=override.max_tokens or self.max_tokens,
-        )
+
+        changes = {
+            field.name: getattr(override, field.name)
+            for field in fields(self)
+            if getattr(override, field.name) is not None
+        }
+        return replace(self, **changes)

agents/models/openai_chatcompletions.py

@@ -518,6 +518,11 @@ class OpenAIChatCompletionsModel(Model):
                 f"Response format: {response_format}\n"
             )
 
+        # Match the behavior of Responses where store is True when not given
+        store = model_settings.store if model_settings.store is not None else True
+
+        reasoning_effort = model_settings.reasoning.effort if model_settings.reasoning else None
+
         ret = await self._get_client().chat.completions.create(
             model=self.model,
             messages=converted_messages,
@@ -532,7 +537,10 @@ class OpenAIChatCompletionsModel(Model):
             parallel_tool_calls=parallel_tool_calls,
             stream=stream,
             stream_options={"include_usage": True} if stream else NOT_GIVEN,
+            store=store,
+            reasoning_effort=self._non_null_or_not_given(reasoning_effort),
             extra_headers=_HEADERS,
+            metadata=model_settings.metadata,
         )
 
         if isinstance(ret, ChatCompletion):
@@ -551,6 +559,7 @@ class OpenAIChatCompletionsModel(Model):
             temperature=model_settings.temperature,
             tools=[],
             parallel_tool_calls=parallel_tool_calls or False,
+            reasoning=model_settings.reasoning,
         )
         return response, ret
 
@@ -757,7 +766,7 @@ class _Converter:
             elif isinstance(c, dict) and c.get("type") == "input_file":
                 raise UserError(f"File uploads are not supported for chat completions {c}")
             else:
-                raise UserError(f"Unknonw content: {c}")
+                raise UserError(f"Unknown content: {c}")
         return out
 
     @classmethod
@@ -919,12 +928,13 @@ class _Converter:
             elif func_call := cls.maybe_function_tool_call(item):
                 asst = ensure_assistant_message()
                 tool_calls = list(asst.get("tool_calls", []))
+                arguments = func_call["arguments"] if func_call["arguments"] else "{}"
                 new_tool_call = ChatCompletionMessageToolCallParam(
                     id=func_call["call_id"],
                     type="function",
                     function={
                         "name": func_call["name"],
-                        "arguments": func_call["arguments"],
+                        "arguments": arguments,
                     },
                 )
                 tool_calls.append(new_tool_call)
@@ -967,7 +977,7 @@ class ToolConverter:
             }
 
         raise UserError(
-            f"Hosted tools are not supported with the ChatCompletions API. FGot tool type: "
+            f"Hosted tools are not supported with the ChatCompletions API. Got tool type: "
             f"{type(tool)}, tool: {tool}"
         )
 

agents/models/openai_responses.py

@@ -83,7 +83,7 @@ class OpenAIResponsesModel(Model):
                 )
 
                 if _debug.DONT_LOG_MODEL_DATA:
-                    logger.debug("LLM responsed")
+                    logger.debug("LLM responded")
                 else:
                     logger.debug(
                         "LLM resp:\n"
@@ -208,7 +208,11 @@ class OpenAIResponsesModel(Model):
         list_input = ItemHelpers.input_to_new_input_list(input)
 
         parallel_tool_calls = (
-            True if model_settings.parallel_tool_calls and tools and len(tools) > 0 else NOT_GIVEN
+            True
+            if model_settings.parallel_tool_calls and tools and len(tools) > 0
+            else False
+            if model_settings.parallel_tool_calls is False
+            else NOT_GIVEN
         )
 
         tool_choice = Converter.convert_tool_choice(model_settings.tool_choice)
@@ -242,6 +246,9 @@ class OpenAIResponsesModel(Model):
             stream=stream,
             extra_headers=_HEADERS,
             text=response_format,
+            store=self._non_null_or_not_given(model_settings.store),
+            reasoning=self._non_null_or_not_given(model_settings.reasoning),
+            metadata=model_settings.metadata,
         )
 
     def _get_client(self) -> AsyncOpenAI:

agents/py.typed

@@ -0,0 +1 @@
+