openai-agents 0.0.15__tar.gz → 0.0.17__tar.gz

openai_agents-0.0.17/AGENTS.md

@@ -0,0 +1,69 @@
+Welcome to the OpenAI Agents SDK repository. This file contains the main points for new contributors.
+
+## Repository overview
+
+- **Source code**: `src/agents/` contains the implementation.
+- **Tests**: `tests/` with a short guide in `tests/README.md`.
+- **Examples**: under `examples/`.
+- **Documentation**: markdown pages live in `docs/` with `mkdocs.yml` controlling the site.
+- **Utilities**: developer commands are defined in the `Makefile`.
+- **PR template**: `.github/PULL_REQUEST_TEMPLATE/pull_request_template.md` describes the information every PR must include.
+
+## Local workflow
+
+1. Format, lint and type‑check your changes:
+
+   ```bash
+   make format
+   make lint
+   make mypy
+   ```
+
+2. Run the tests:
+
+   ```bash
+   make tests
+   ```
+
+   To run a single test, use `uv run pytest -s -k <test_name>`.
+
+3. Build the documentation (optional but recommended for docs changes):
+
+   ```bash
+   make build-docs
+   ```
+
+   Coverage can be generated with `make coverage`.
+
+## Snapshot tests
+
+Some tests rely on inline snapshots. See `tests/README.md` for details on updating them:
+
+```bash
+make snapshots-fix      # update existing snapshots
+make snapshots-create   # create new snapshots
+```
+
+Run `make tests` again after updating snapshots to ensure they pass.
+
+## Style notes
+
+- Write comments as full sentences and end them with a period.
+
+## Pull request expectations
+
+PRs should use the template located at `.github/PULL_REQUEST_TEMPLATE/pull_request_template.md`. Provide a summary, test plan and issue number if applicable, then check that:
+
+- New tests are added when needed.
+- Documentation is updated.
+- `make lint` and `make format` have been run.
+- The full test suite passes.
+
+Commit messages should be concise and written in the imperative mood. Small, focused commits are preferred.
+
+## What reviewers look for
+
+- Tests covering new behaviour.
+- Consistent style: code formatted with `ruff format`, imports sorted, and type hints passing `mypy`.
+- Clear documentation for any public API changes.
+- Clean history and a helpful PR description.

{openai_agents-0.0.15 → openai_agents-0.0.17}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: openai-agents
-Version: 0.0.15
+Version: 0.0.17
 Summary: OpenAI Agents SDK
 Project-URL: Homepage, https://github.com/openai/openai-agents-python
 Project-URL: Repository, https://github.com/openai/openai-agents-python
@@ -20,7 +20,7 @@ Classifier: Typing :: Typed
 Requires-Python: >=3.9
 Requires-Dist: griffe<2,>=1.5.6
 Requires-Dist: mcp<2,>=1.8.0; python_version >= '3.10'
-Requires-Dist: openai>=1.76.0
+Requires-Dist: openai>=1.81.0
 Requires-Dist: pydantic<3,>=2.10
 Requires-Dist: requests<3,>=2.0
 Requires-Dist: types-requests<3,>=2.0

{openai_agents-0.0.15 → openai_agents-0.0.17}/docs/ja/mcp.md

@@ -12,12 +12,13 @@ Agents SDK は MCP をサポートしており、これにより幅広い MCP
 
 ## MCP サーバー
 
-現在、MCP 仕様では使用するトランスポート方式に基づき 2 種類のサーバーが定義されています。
+現在、MCP 仕様では使用するトランスポート方式に基づき 3 種類のサーバーが定義されています。
 
-1. **stdio** サーバー: アプリケーションのサブプロセスとして実行されます。ローカルで動かすイメージです。  
+1. **stdio** サーバー: アプリケーションのサブプロセスとして実行されます。ローカルで動かすイメージです。
 2. **HTTP over SSE** サーバー: リモートで動作し、 URL 経由で接続します。
+3. **Streamable HTTP** サーバー: MCP 仕様に定義された Streamable HTTP トランスポートを使用してリモートで動作します。
 
-これらのサーバーへは [`MCPServerStdio`][agents.mcp.server.MCPServerStdio] と [`MCPServerSse`][agents.mcp.server.MCPServerSse] クラスを使用して接続できます。
+これらのサーバーへは [`MCPServerStdio`][agents.mcp.server.MCPServerStdio]、[`MCPServerSse`][agents.mcp.server.MCPServerSse]、[`MCPServerStreamableHttp`][agents.mcp.server.MCPServerStreamableHttp] クラスを使用して接続できます。
 
 たとえば、[公式 MCP filesystem サーバー](https://www.npmjs.com/package/@modelcontextprotocol/server-filesystem)を利用する場合は次のようになります。
 
@@ -46,7 +47,7 @@ agent=Agent(
 
 ## キャッシュ
 
-エージェントが実行されるたびに、MCP サーバーへ `list_tools()` が呼び出されます。サーバーがリモートの場合は特にレイテンシが発生します。ツール一覧を自動でキャッシュしたい場合は、[`MCPServerStdio`][agents.mcp.server.MCPServerStdio] と [`MCPServerSse`][agents.mcp.server.MCPServerSse] の両方に `cache_tools_list=True` を渡してください。ツール一覧が変更されないと確信できる場合のみ使用してください。
+エージェントが実行されるたびに、MCP サーバーへ `list_tools()` が呼び出されます。サーバーがリモートの場合は特にレイテンシが発生します。ツール一覧を自動でキャッシュしたい場合は、[`MCPServerStdio`][agents.mcp.server.MCPServerStdio]、[`MCPServerSse`][agents.mcp.server.MCPServerSse]、[`MCPServerStreamableHttp`][agents.mcp.server.MCPServerStreamableHttp] の各クラスに `cache_tools_list=True` を渡してください。ツール一覧が変更されないと確信できる場合のみ使用してください。
 
 キャッシュを無効化したい場合は、サーバーで `invalidate_tools_cache()` を呼び出します。
 

{openai_agents-0.0.15 → openai_agents-0.0.17}/docs/ja/tools.md

@@ -17,6 +17,10 @@ OpenAI は [`OpenAIResponsesModel`][agents.models.openai_responses.OpenAIRespons
 -   [`WebSearchTool`][agents.tool.WebSearchTool] はエージェントに Web 検索を行わせます。
 -   [`FileSearchTool`][agents.tool.FileSearchTool] は OpenAI ベクトルストアから情報を取得します。
 -   [`ComputerTool`][agents.tool.ComputerTool] はコンピュータ操作タスクを自動化します。
+-   [`CodeInterpreterTool`][agents.tool.CodeInterpreterTool] はサンドボックス環境でコードを実行します。
+-   [`HostedMCPTool`][agents.tool.HostedMCPTool] はリモート MCP サーバーのツールをモデルから直接利用できるようにします。
+-   [`ImageGenerationTool`][agents.tool.ImageGenerationTool] はプロンプトから画像を生成します。
+-   [`LocalShellTool`][agents.tool.LocalShellTool] はローカルマシンでシェルコマンドを実行します。
 
 ```python
 from agents import Agent, FileSearchTool, Runner, WebSearchTool

{openai_agents-0.0.15 → openai_agents-0.0.17}/docs/ja/tracing.md

@@ -119,4 +119,5 @@ async def main():
 -   [Comet Opik](https://www.comet.com/docs/opik/tracing/integrations/openai_agents)
 -   [Langfuse](https://langfuse.com/docs/integrations/openaiagentssdk/openai-agents)
 -   [Langtrace](https://docs.langtrace.ai/supported-integrations/llm-frameworks/openai-agents-sdk)
--   [Okahu‑Monocle](https://github.com/monocle2ai/monocle)
+-   [Okahu‑Monocle](https://github.com/monocle2ai/monocle)
+-   [Portkey AI](https://portkey.ai/docs/integrations/agents/openai-agents)

{openai_agents-0.0.15 → openai_agents-0.0.17}/docs/mcp.md

@@ -8,12 +8,13 @@ The Agents SDK has support for MCP. This enables you to use a wide range of MCP
 
 ## MCP servers
 
-Currently, the MCP spec defines two kinds of servers, based on the transport mechanism they use:
+Currently, the MCP spec defines three kinds of servers, based on the transport mechanism they use:
 
 1. **stdio** servers run as a subprocess of your application. You can think of them as running "locally".
 2. **HTTP over SSE** servers run remotely. You connect to them via a URL.
+3. **Streamable HTTP** servers run remotely using the Streamable HTTP transport defined in the MCP spec.
 
-You can use the [`MCPServerStdio`][agents.mcp.server.MCPServerStdio] and [`MCPServerSse`][agents.mcp.server.MCPServerSse] classes to connect to these servers.
+You can use the [`MCPServerStdio`][agents.mcp.server.MCPServerStdio], [`MCPServerSse`][agents.mcp.server.MCPServerSse], and [`MCPServerStreamableHttp`][agents.mcp.server.MCPServerStreamableHttp] classes to connect to these servers.
 
 For example, this is how you'd use the [official MCP filesystem server](https://www.npmjs.com/package/@modelcontextprotocol/server-filesystem).
 
@@ -42,7 +43,7 @@ agent=Agent(
 
 ## Caching
 
-Every time an Agent runs, it calls `list_tools()` on the MCP server. This can be a latency hit, especially if the server is a remote server. To automatically cache the list of tools, you can pass `cache_tools_list=True` to both [`MCPServerStdio`][agents.mcp.server.MCPServerStdio] and [`MCPServerSse`][agents.mcp.server.MCPServerSse]. You should only do this if you're certain the tool list will not change.
+Every time an Agent runs, it calls `list_tools()` on the MCP server. This can be a latency hit, especially if the server is a remote server. To automatically cache the list of tools, you can pass `cache_tools_list=True` to [`MCPServerStdio`][agents.mcp.server.MCPServerStdio], [`MCPServerSse`][agents.mcp.server.MCPServerSse], and [`MCPServerStreamableHttp`][agents.mcp.server.MCPServerStreamableHttp]. You should only do this if you're certain the tool list will not change.
 
 If you want to invalidate the cache, you can call `invalidate_tools_cache()` on the servers.
 

{openai_agents-0.0.15 → openai_agents-0.0.17}/docs/tools.md

@@ -13,6 +13,10 @@ OpenAI offers a few built-in tools when using the [`OpenAIResponsesModel`][agent
 -   The [`WebSearchTool`][agents.tool.WebSearchTool] lets an agent search the web.
 -   The [`FileSearchTool`][agents.tool.FileSearchTool] allows retrieving information from your OpenAI Vector Stores.
 -   The [`ComputerTool`][agents.tool.ComputerTool] allows automating computer use tasks.
+-   The [`CodeInterpreterTool`][agents.tool.CodeInterpreterTool] lets the LLM execute code in a sandboxed environment.
+-   The [`HostedMCPTool`][agents.tool.HostedMCPTool] exposes a remote MCP server's tools to the model.
+-   The [`ImageGenerationTool`][agents.tool.ImageGenerationTool] generates images from a prompt.
+-   The [`LocalShellTool`][agents.tool.LocalShellTool] runs shell commands on your machine.
 
 ```python
 from agents import Agent, FileSearchTool, Runner, WebSearchTool
@@ -266,7 +270,7 @@ The `agent.as_tool` function is a convenience method to make it easy to turn an
 ```python
 @function_tool
 async def run_my_agent() -> str:
-  """A tool that runs the agent with custom configs".
+    """A tool that runs the agent with custom configs"""
 
     agent = Agent(name="My agent", instructions="...")
 

{openai_agents-0.0.15 → openai_agents-0.0.17}/docs/tracing.md

@@ -115,3 +115,5 @@ To customize this default setup, to send traces to alternative or additional bac
 -   [Langfuse](https://langfuse.com/docs/integrations/openaiagentssdk/openai-agents)
 -   [Langtrace](https://docs.langtrace.ai/supported-integrations/llm-frameworks/openai-agents-sdk)
 -   [Okahu-Monocle](https://github.com/monocle2ai/monocle)
+-   [Galileo](https://v2docs.galileo.ai/integrations/openai-agent-integration#openai-agent-integration)
+-   [Portkey AI](https://portkey.ai/docs/integrations/agents/openai-agents)

{openai_agents-0.0.15 → openai_agents-0.0.17}/examples/agent_patterns/input_guardrails.py

@@ -20,7 +20,7 @@ This example shows how to use guardrails.
 Guardrails are checks that run in parallel to the agent's execution.
 They can be used to do things like:
 - Check if input messages are off-topic
-- Check that output messages don't violate any policies
+- Check that input messages don't violate any policies
 - Take over control of the agent's execution if an unexpected input is detected
 
 In this example, we'll setup an input guardrail that trips if the user is asking to do math homework.

openai_agents-0.0.17/examples/hosted_mcp/approvals.py

@@ -0,0 +1,61 @@
+import argparse
+import asyncio
+
+from agents import (
+    Agent,
+    HostedMCPTool,
+    MCPToolApprovalFunctionResult,
+    MCPToolApprovalRequest,
+    Runner,
+)
+
+"""This example demonstrates how to use the hosted MCP support in the OpenAI Responses API, with
+approval callbacks."""
+
+
+def approval_callback(request: MCPToolApprovalRequest) -> MCPToolApprovalFunctionResult:
+    answer = input(f"Approve running the tool `{request.data.name}`? (y/n) ")
+    result: MCPToolApprovalFunctionResult = {"approve": answer == "y"}
+    if not result["approve"]:
+        result["reason"] = "User denied"
+    return result
+
+
+async def main(verbose: bool, stream: bool):
+    agent = Agent(
+        name="Assistant",
+        tools=[
+            HostedMCPTool(
+                tool_config={
+                    "type": "mcp",
+                    "server_label": "gitmcp",
+                    "server_url": "https://gitmcp.io/openai/codex",
+                    "require_approval": "always",
+                },
+                on_approval_request=approval_callback,
+            )
+        ],
+    )
+
+    if stream:
+        result = Runner.run_streamed(agent, "Which language is this repo written in?")
+        async for event in result.stream_events():
+            if event.type == "run_item_stream_event":
+                print(f"Got event of type {event.item.__class__.__name__}")
+        print(f"Done streaming; final result: {result.final_output}")
+    else:
+        res = await Runner.run(agent, "Which language is this repo written in?")
+        print(res.final_output)
+
+    if verbose:
+        for item in res.new_items:
+            print(item)
+
+
+if __name__ == "__main__":
+    parser = argparse.ArgumentParser()
+    parser.add_argument("--verbose", action="store_true", default=False)
+    parser.add_argument("--stream", action="store_true", default=False)
+    args = parser.parse_args()
+
+    asyncio.run(main(args.verbose, args.stream))

openai_agents-0.0.17/examples/hosted_mcp/simple.py

@@ -0,0 +1,47 @@
+import argparse
+import asyncio
+
+from agents import Agent, HostedMCPTool, Runner
+
+"""This example demonstrates how to use the hosted MCP support in the OpenAI Responses API, with
+approvals not required for any tools. You should only use this for trusted MCP servers."""
+
+
+async def main(verbose: bool, stream: bool):
+    agent = Agent(
+        name="Assistant",
+        tools=[
+            HostedMCPTool(
+                tool_config={
+                    "type": "mcp",
+                    "server_label": "gitmcp",
+                    "server_url": "https://gitmcp.io/openai/codex",
+                    "require_approval": "never",
+                }
+            )
+        ],
+    )
+
+    if stream:
+        result = Runner.run_streamed(agent, "Which language is this repo written in?")
+        async for event in result.stream_events():
+            if event.type == "run_item_stream_event":
+                print(f"Got event of type {event.item.__class__.__name__}")
+        print(f"Done streaming; final result: {result.final_output}")
+    else:
+        res = await Runner.run(agent, "Which language is this repo written in?")
+        print(res.final_output)
+        # The repository is primarily written in multiple languages, including Rust and TypeScript...
+
+    if verbose:
+        for item in res.new_items:
+            print(item)
+
+
+if __name__ == "__main__":
+    parser = argparse.ArgumentParser()
+    parser.add_argument("--verbose", action="store_true", default=False)
+    parser.add_argument("--stream", action="store_true", default=False)
+    args = parser.parse_args()
+
+    asyncio.run(main(args.verbose, args.stream))

openai_agents-0.0.17/examples/tools/code_interpreter.py

@@ -0,0 +1,34 @@
+import asyncio
+
+from agents import Agent, CodeInterpreterTool, Runner, trace
+
+
+async def main():
+    agent = Agent(
+        name="Code interpreter",
+        instructions="You love doing math.",
+        tools=[
+            CodeInterpreterTool(
+                tool_config={"type": "code_interpreter", "container": {"type": "auto"}},
+            )
+        ],
+    )
+
+    with trace("Code interpreter example"):
+        print("Solving math problem...")
+        result = Runner.run_streamed(agent, "What is the square root of273 * 312821 plus 1782?")
+        async for event in result.stream_events():
+            if (
+                event.type == "run_item_stream_event"
+                and event.item.type == "tool_call_item"
+                and event.item.raw_item.type == "code_interpreter_call"
+            ):
+                print(f"Code interpreter code:\n```\n{event.item.raw_item.code}\n```\n")
+            elif event.type == "run_item_stream_event":
+                print(f"Other event: {event.item.type}")
+
+        print(f"Final output: {result.final_output}")
+
+
+if __name__ == "__main__":
+    asyncio.run(main())

openai_agents-0.0.17/examples/tools/image_generator.py

@@ -0,0 +1,54 @@
+import asyncio
+import base64
+import os
+import subprocess
+import sys
+import tempfile
+
+from agents import Agent, ImageGenerationTool, Runner, trace
+
+
+def open_file(path: str) -> None:
+    if sys.platform.startswith("darwin"):
+        subprocess.run(["open", path], check=False)  # macOS
+    elif os.name == "nt":  # Windows
+        os.astartfile(path)  # type: ignore
+    elif os.name == "posix":
+        subprocess.run(["xdg-open", path], check=False)  # Linux/Unix
+    else:
+        print(f"Don't know how to open files on this platform: {sys.platform}")
+
+
+async def main():
+    agent = Agent(
+        name="Image generator",
+        instructions="You are a helpful agent.",
+        tools=[
+            ImageGenerationTool(
+                tool_config={"type": "image_generation", "quality": "low"},
+            )
+        ],
+    )
+
+    with trace("Image generation example"):
+        print("Generating image, this may take a while...")
+        result = await Runner.run(
+            agent, "Create an image of a frog eating a pizza, comic book style."
+        )
+        print(result.final_output)
+        for item in result.new_items:
+            if (
+                item.type == "tool_call_item"
+                and item.raw_item.type == "image_generation_call"
+                and (img_result := item.raw_item.result)
+            ):
+                with tempfile.NamedTemporaryFile(suffix=".png", delete=False) as tmp:
+                    tmp.write(base64.b64decode(img_result))
+                    temp_path = tmp.name
+
+                # Open the image
+                open_file(temp_path)
+
+
+if __name__ == "__main__":
+    asyncio.run(main())

{openai_agents-0.0.15 → openai_agents-0.0.17}/pyproject.toml

@@ -1,13 +1,13 @@
 [project]
 name = "openai-agents"
-version = "0.0.15"
+version = "0.0.17"
 description = "OpenAI Agents SDK"
 readme = "README.md"
 requires-python = ">=3.9"
 license = "MIT"
 authors = [{ name = "OpenAI", email = "support@openai.com" }]
 dependencies = [
-    "openai>=1.76.0",
+    "openai>=1.81.0",
     "pydantic>=2.10, <3",
     "griffe>=1.5.6, <2",
     "typing-extensions>=4.12.2, <5",

{openai_agents-0.0.15 → openai_agents-0.0.17}/src/agents/__init__.py

@@ -14,6 +14,7 @@ from .exceptions import (
     MaxTurnsExceeded,
     ModelBehaviorError,
     OutputGuardrailTripwireTriggered,
+    RunErrorDetails,
     UserError,
 )
 from .guardrail import (
@@ -54,10 +55,19 @@ from .stream_events import (
     StreamEvent,
 )
 from .tool import (
+    CodeInterpreterTool,
     ComputerTool,
     FileSearchTool,
     FunctionTool,
     FunctionToolResult,
+    HostedMCPTool,
+    ImageGenerationTool,
+    LocalShellCommandRequest,
+    LocalShellExecutor,
+    LocalShellTool,
+    MCPToolApprovalFunction,
+    MCPToolApprovalFunctionResult,
+    MCPToolApprovalRequest,
     Tool,
     WebSearchTool,
     default_tool_error_function,
@@ -195,6 +205,7 @@ __all__ = [
     "AgentHooks",
     "RunContextWrapper",
     "TContext",
+    "RunErrorDetails",
     "RunResult",
     "RunResultStreaming",
     "RunConfig",
@@ -206,8 +217,17 @@ __all__ = [
     "FunctionToolResult",
     "ComputerTool",
     "FileSearchTool",
+    "CodeInterpreterTool",
+    "ImageGenerationTool",
+    "LocalShellCommandRequest",
+    "LocalShellExecutor",
+    "LocalShellTool",
     "Tool",
     "WebSearchTool",
+    "HostedMCPTool",
+    "MCPToolApprovalFunction",
+    "MCPToolApprovalRequest",
+    "MCPToolApprovalFunctionResult",
     "function_tool",
     "Usage",
     "add_trace_processor",