openai-agents 0.0.16__tar.gz → 0.0.18__tar.gz

{openai_agents-0.0.16 → openai_agents-0.0.18}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: openai-agents
-Version: 0.0.16
+Version: 0.0.18
 Summary: OpenAI Agents SDK
 Project-URL: Homepage, https://github.com/openai/openai-agents-python
 Project-URL: Repository, https://github.com/openai/openai-agents-python
@@ -19,8 +19,8 @@ Classifier: Topic :: Software Development :: Libraries :: Python Modules
 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.81.0
+Requires-Dist: mcp<2,>=1.9.4; python_version >= '3.10'
+Requires-Dist: openai>=1.87.0
 Requires-Dist: pydantic<3,>=2.10
 Requires-Dist: requests<3,>=2.0
 Requires-Dist: types-requests<3,>=2.0
@@ -40,6 +40,9 @@ The OpenAI Agents SDK is a lightweight yet powerful framework for building multi
 
 <img src="https://cdn.openai.com/API/docs/images/orchestration.png" alt="Image of the Agents Tracing UI" style="max-height: 803px;">
 
+> [!NOTE]
+> Looking for the JavaScript/TypeScript version? Check out [Agents SDK JS/TS](https://github.com/openai/openai-agents-js).
+
 ### Core concepts:
 
 1. [**Agents**](https://openai.github.io/openai-agents-python/agents): LLMs configured with instructions, tools, guardrails, and handoffs

{openai_agents-0.0.16 → openai_agents-0.0.18}/README.md

@@ -4,6 +4,9 @@ The OpenAI Agents SDK is a lightweight yet powerful framework for building multi
 
 <img src="https://cdn.openai.com/API/docs/images/orchestration.png" alt="Image of the Agents Tracing UI" style="max-height: 803px;">
 
+> [!NOTE]
+> Looking for the JavaScript/TypeScript version? Check out [Agents SDK JS/TS](https://github.com/openai/openai-agents-js).
+
 ### Core concepts:
 
 1. [**Agents**](https://openai.github.io/openai-agents-python/agents): LLMs configured with instructions, tools, guardrails, and handoffs

{openai_agents-0.0.16 → openai_agents-0.0.18}/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.18/docs/ja/repl.md

@@ -0,0 +1,22 @@
+---
+search:
+  exclude: true
+---
+# REPL ユーティリティ
+
+`run_demo_loop` を使うと、ターミナルから手軽にエージェントを試せます。
+
+```python
+import asyncio
+from agents import Agent, run_demo_loop
+
+async def main() -> None:
+    agent = Agent(name="Assistant", instructions="あなたは親切なアシスタントです")
+    await run_demo_loop(agent)
+
+if __name__ == "__main__":
+    asyncio.run(main())
+```
+
+`run_demo_loop` は入力を繰り返し受け取り、会話履歴を保持したままエージェントを実行します。既定ではストリーミング出力を表示します。
+`quit` または `exit` と入力するか `Ctrl-D` を押すと終了します。

{openai_agents-0.0.16 → openai_agents-0.0.18}/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.16 → openai_agents-0.0.18}/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.16 → openai_agents-0.0.18}/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.18/docs/ref/repl.md

@@ -0,0 +1,6 @@
+# `repl`
+
+::: agents.repl
+    options:
+        members:
+            - run_demo_loop

openai_agents-0.0.18/docs/release.md

@@ -0,0 +1,18 @@
+# Release process
+
+The project follows a slightly modified version of semantic versioning using the form `0.Y.Z`. The leading `0` indicates the SDK is still evolving rapidly. Increment the components as follows:
+
+## Minor (`Y`) versions
+
+We will increase minor versions `Y` for **breaking changes** to any public interfaces that are not marked as beta. For example, going from `0.0.x` to `0.1.x` might include breaking changes.
+
+If you don't want breaking changes, we recommend pinning to `0.0.x` versions in your project.
+
+## Patch (`Z`) versions
+
+We will increment `Z` for non-breaking changes:
+
+- Bug fixes
+- New features
+- Changes to private interfaces
+- Updates to beta features

openai_agents-0.0.18/docs/repl.md

@@ -0,0 +1,19 @@
+# REPL utility
+
+The SDK provides `run_demo_loop` for quick interactive testing.
+
+```python
+import asyncio
+from agents import Agent, run_demo_loop
+
+async def main() -> None:
+    agent = Agent(name="Assistant", instructions="You are a helpful assistant.")
+    await run_demo_loop(agent)
+
+if __name__ == "__main__":
+    asyncio.run(main())
+```
+
+`run_demo_loop` prompts for user input in a loop, keeping the conversation
+history between turns. By default it streams model output as it is produced.
+Type `quit` or `exit` (or press `Ctrl-D`) to leave the loop.

{openai_agents-0.0.16 → openai_agents-0.0.18}/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="...")
 
@@ -280,6 +284,33 @@ async def run_my_agent() -> str:
     return str(result.final_output)
 ```
 
+### Custom output extraction
+
+In certain cases, you might want to modify the output of the tool-agents before returning it to the central agent. This may be useful if you want to:
+
+- Extract a specific piece of information (e.g., a JSON payload) from the sub-agent's chat history.
+- Convert or reformat the agent’s final answer (e.g., transform Markdown into plain text or CSV).
+- Validate the output or provide a fallback value when the agent’s response is missing or malformed.
+
+You can do this by supplying the `custom_output_extractor` argument to the `as_tool` method:
+
+```python
+async def extract_json_payload(run_result: RunResult) -> str:
+    # Scan the agent’s outputs in reverse order until we find a JSON-like message from a tool call.
+    for item in reversed(run_result.new_items):
+        if isinstance(item, ToolCallOutputItem) and item.output.strip().startswith("{"):
+            return item.output.strip()
+    # Fallback to an empty JSON object if nothing was found
+    return "{}"
+
+
+json_tool = data_agent.as_tool(
+    tool_name="get_data_json",
+    tool_description="Run the data agent and return only its JSON payload",
+    custom_output_extractor=extract_json_payload,
+)
+```
+
 ## Handling errors in function tools
 
 When you create a function tool via `@function_tool`, you can pass a `failure_error_function`. This is a function that provides an error response to the LLM in case the tool call crashes.

{openai_agents-0.0.16 → openai_agents-0.0.18}/docs/tracing.md

@@ -116,3 +116,4 @@ To customize this default setup, to send traces to alternative or additional bac
 -   [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.16 → openai_agents-0.0.18}/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.18/examples/basic/prompt_template.py

@@ -0,0 +1,79 @@
+import argparse
+import asyncio
+import random
+
+from agents import Agent, GenerateDynamicPromptData, Runner
+
+"""
+NOTE: This example will not work out of the box, because the default prompt ID will not be available
+in your project.
+
+To use it, please:
+1. Go to https://platform.openai.com/playground/prompts
+2. Create a new prompt variable, `poem_style`.
+3. Create a system prompt with the content:
+```
+Write a poem in {{poem_style}}
+```
+4. Run the example with the `--prompt-id` flag.
+"""
+
+DEFAULT_PROMPT_ID = "pmpt_6850729e8ba481939fd439e058c69ee004afaa19c520b78b"
+
+
+class DynamicContext:
+    def __init__(self, prompt_id: str):
+        self.prompt_id = prompt_id
+        self.poem_style = random.choice(["limerick", "haiku", "ballad"])
+        print(f"[debug] DynamicContext initialized with poem_style: {self.poem_style}")
+
+
+async def _get_dynamic_prompt(data: GenerateDynamicPromptData):
+    ctx: DynamicContext = data.context.context
+    return {
+        "id": ctx.prompt_id,
+        "version": "1",
+        "variables": {
+            "poem_style": ctx.poem_style,
+        },
+    }
+
+
+async def dynamic_prompt(prompt_id: str):
+    context = DynamicContext(prompt_id)
+
+    agent = Agent(
+        name="Assistant",
+        prompt=_get_dynamic_prompt,
+    )
+
+    result = await Runner.run(agent, "Tell me about recursion in programming.", context=context)
+    print(result.final_output)
+
+
+async def static_prompt(prompt_id: str):
+    agent = Agent(
+        name="Assistant",
+        prompt={
+            "id": prompt_id,
+            "version": "1",
+            "variables": {
+                "poem_style": "limerick",
+            },
+        },
+    )
+
+    result = await Runner.run(agent, "Tell me about recursion in programming.")
+    print(result.final_output)
+
+
+if __name__ == "__main__":
+    parser = argparse.ArgumentParser()
+    parser.add_argument("--dynamic", action="store_true")
+    parser.add_argument("--prompt-id", type=str, default=DEFAULT_PROMPT_ID)
+    args = parser.parse_args()
+
+    if args.dynamic:
+        asyncio.run(dynamic_prompt(args.prompt_id))
+    else:
+        asyncio.run(static_prompt(args.prompt_id))

{openai_agents-0.0.16 → openai_agents-0.0.18}/examples/hosted_mcp/approvals.py

@@ -48,7 +48,7 @@ async def main(verbose: bool, stream: bool):
         print(res.final_output)
 
     if verbose:
-        for item in result.new_items:
+        for item in res.new_items:
             print(item)
 
 

{openai_agents-0.0.16 → openai_agents-0.0.18}/examples/hosted_mcp/simple.py

@@ -34,7 +34,7 @@ async def main(verbose: bool, stream: bool):
         # The repository is primarily written in multiple languages, including Rust and TypeScript...
 
     if verbose:
-        for item in result.new_items:
+        for item in res.new_items:
             print(item)
 
 

{openai_agents-0.0.16 → openai_agents-0.0.18}/mkdocs.yml

@@ -59,6 +59,7 @@ plugins:
                 - running_agents.md
                 - results.md
                 - streaming.md
+                - repl.md
                 - tools.md
                 - mcp.md
                 - handoffs.md
@@ -71,6 +72,7 @@ plugins:
                     - models/litellm.md
                 - config.md
                 - visualization.md
+                - release.md
                 - Voice agents:
                     - voice/quickstart.md
                     - voice/pipeline.md
@@ -80,6 +82,7 @@ plugins:
                     - ref/index.md
                     - ref/agent.md
                     - ref/run.md
+                    - ref/repl.md
                     - ref/tool.md
                     - ref/result.md
                     - ref/stream_events.md
@@ -139,6 +142,7 @@ plugins:
                 - running_agents.md
                 - results.md
                 - streaming.md
+                - repl.md
                 - tools.md
                 - mcp.md
                 - handoffs.md

{openai_agents-0.0.16 → openai_agents-0.0.18}/pyproject.toml

@@ -1,19 +1,19 @@
 [project]
 name = "openai-agents"
-version = "0.0.16"
+version = "0.0.18"
 description = "OpenAI Agents SDK"
 readme = "README.md"
 requires-python = ">=3.9"
 license = "MIT"
 authors = [{ name = "OpenAI", email = "support@openai.com" }]
 dependencies = [
-    "openai>=1.81.0",
+    "openai>=1.87.0",
     "pydantic>=2.10, <3",
     "griffe>=1.5.6, <2",
     "typing-extensions>=4.12.2, <5",
     "requests>=2.0, <3",
     "types-requests>=2.0, <3",
-    "mcp>=1.8.0, <2; python_version >= '3.10'",
+    "mcp>=1.9.4, <2; python_version >= '3.10'",
 ]
 classifiers = [
     "Typing :: Typed",

{openai_agents-0.0.16 → openai_agents-0.0.18}/src/agents/__init__.py

@@ -14,6 +14,7 @@ from .exceptions import (
     MaxTurnsExceeded,
     ModelBehaviorError,
     OutputGuardrailTripwireTriggered,
+    RunErrorDetails,
     UserError,
 )
 from .guardrail import (
@@ -44,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
@@ -159,6 +162,7 @@ __all__ = [
     "ToolsToFinalOutputFunction",
     "ToolsToFinalOutputResult",
     "Runner",
+    "run_demo_loop",
     "Model",
     "ModelProvider",
     "ModelTracing",
@@ -175,6 +179,9 @@ __all__ = [
     "AgentsException",
     "InputGuardrailTripwireTriggered",
     "OutputGuardrailTripwireTriggered",
+    "DynamicPromptFunction",
+    "GenerateDynamicPromptData",
+    "Prompt",
     "MaxTurnsExceeded",
     "ModelBehaviorError",
     "UserError",
@@ -204,6 +211,7 @@ __all__ = [
     "AgentHooks",
     "RunContextWrapper",
     "TContext",
+    "RunErrorDetails",
     "RunResult",
     "RunResultStreaming",
     "RunConfig",

{openai_agents-0.0.16 → openai_agents-0.0.18}/src/agents/_run_impl.py

@@ -33,6 +33,7 @@ from openai.types.responses.response_output_item import (
     ImageGenerationCall,
     LocalShellCall,
     McpApprovalRequest,
+    McpCall,
     McpListTools,
 )
 from openai.types.responses.response_reasoning_item import ResponseReasoningItem
@@ -74,6 +75,7 @@ from .tool import (
     MCPToolApprovalRequest,
     Tool,
 )
+from .tool_context import ToolContext
 from .tracing import (
     SpanError,
     Trace,
@@ -456,6 +458,9 @@ class RunImpl:
                         )
             elif isinstance(output, McpListTools):
                 items.append(MCPListToolsItem(raw_item=output, agent=agent))
+            elif isinstance(output, McpCall):
+                items.append(ToolCallItem(raw_item=output, agent=agent))
+                tools_used.append("mcp")
             elif isinstance(output, ImageGenerationCall):
                 items.append(ToolCallItem(raw_item=output, agent=agent))
                 tools_used.append("image_generation")
@@ -539,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()
                         ),

{openai_agents-0.0.16 → openai_agents-0.0.18}/src/agents/agent.py

@@ -1,11 +1,13 @@
 from __future__ import annotations
 
+import asyncio
 import dataclasses
 import inspect
 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
@@ -16,8 +18,9 @@ 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 FunctionToolResult, Tool, function_tool
+from .tool import FunctionTool, FunctionToolResult, Tool, function_tool
 from .util import _transforms
 from .util._types import MaybeAwaitable
 
@@ -94,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.
@@ -241,12 +250,33 @@ 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)
         return await MCPUtil.get_all_function_tools(self.mcp_servers, convert_schemas_to_strict)
 
-    async def get_all_tools(self) -> list[Tool]:
+    async def get_all_tools(self, run_context: RunContextWrapper[Any]) -> list[Tool]:
         """All agent tools, including MCP tools and function tools."""
         mcp_tools = await self.get_mcp_tools()
-        return mcp_tools + self.tools
+
+        async def _check_tool_enabled(tool: Tool) -> bool:
+            if not isinstance(tool, FunctionTool):
+                return True
+
+            attr = tool.is_enabled
+            if isinstance(attr, bool):
+                return attr
+            res = attr(run_context, self)
+            if inspect.isawaitable(res):
+                return bool(await res)
+            return bool(res)
+
+        results = await asyncio.gather(*(_check_tool_enabled(t) for t in self.tools))
+        enabled: list[Tool] = [t for t, ok in zip(self.tools, results) if ok]
+        return [*mcp_tools, *enabled]

{openai_agents-0.0.16 → openai_agents-0.0.18}/src/agents/agent_output.py

@@ -38,7 +38,7 @@ class AgentOutputSchemaBase(abc.ABC):
     @abc.abstractmethod
     def is_strict_json_schema(self) -> bool:
         """Whether the JSON schema is in strict mode. Strict mode constrains the JSON schema
-        features, but guarantees valis JSON. See here for details:
+        features, but guarantees valid JSON. See here for details:
         https://platform.openai.com/docs/guides/structured-outputs#supported-schemas
         """
         pass