From 586d4b2829d6b34069b15383ea5f2768c1c1e5b0 Mon Sep 17 00:00:00 2001 From: Anees <160124555+maneeshanif@users.noreply.github.com> Date: Tue, 8 Jul 2025 20:10:42 +0500 Subject: [PATCH 1/9] docs: mention 'name' is required in Agent constructor . fix: mention 'name' as required in Agent init doc (#1033) ## What Updated the docs under `docs/agents.md` to clarify that the `name` argument is required when initializing an `Agent`. ## Why Without this clarification, users get a confusing error: `TypeError: Agent.__init__() missing 1 required positional argument: 'name'` This matches the actual constructor in the source code and helps future devs avoid frustration. ## Reference - Source: [`agent.py`](https://github.com/openai/openai-agents-python/blob/main/src/agents/agent.py) --- docs/agents.md | 1 + 1 file changed, 1 insertion(+) diff --git a/docs/agents.md b/docs/agents.md index 39d4afd57..b11a4dd68 100644 --- a/docs/agents.md +++ b/docs/agents.md @@ -6,6 +6,7 @@ Agents are the core building block in your apps. An agent is a large language mo The most common properties of an agent you'll configure are: +- `name`: A required string that identifies your agent. - `instructions`: also known as a developer message or system prompt. - `model`: which LLM to use, and optional `model_settings` to configure model tuning parameters like temperature, top_p, etc. - `tools`: Tools that the agent can use to achieve its tasks. From f09874c6be9d60d2a2c2162132e10a2b5be9afb5 Mon Sep 17 00:00:00 2001 From: Daniel Hashmi <151331476+DanielHashmi@users.noreply.github.com> Date: Tue, 8 Jul 2025 20:14:16 +0500 Subject: [PATCH 2/9] Fix agent lifecycle example output to reflect correct hook execution order (#1015) **Problem:** The expected output in the agent lifecycle example incorrectly shows agent start hooks (`on_start`) running after tool execution and multiple times for the same agent. This misleads developers about when these lifecycle events actually occur. **Solution:** Updated the expected output to accurately reflect the OpenAI Agents framework behavior: - Agent start hooks run immediately when an agent begins execution - Start hooks only run once per agent activation, controlled by the `should_run_agent_start_hooks` flag - After handoffs, the new agent's start hook runs as the first event --- examples/basic/agent_lifecycle_example.py | 6 ++---- examples/basic/lifecycle_example.py | 14 ++++++-------- 2 files changed, 8 insertions(+), 12 deletions(-) diff --git a/examples/basic/agent_lifecycle_example.py b/examples/basic/agent_lifecycle_example.py index 29bb18c96..b4334a83b 100644 --- a/examples/basic/agent_lifecycle_example.py +++ b/examples/basic/agent_lifecycle_example.py @@ -101,12 +101,10 @@ async def main() -> None: ### (Start Agent) 1: Agent Start Agent started ### (Start Agent) 2: Agent Start Agent started tool random_number ### (Start Agent) 3: Agent Start Agent ended tool random_number with result 37 -### (Start Agent) 4: Agent Start Agent started -### (Start Agent) 5: Agent Start Agent handed off to Multiply Agent +### (Start Agent) 4: Agent Start Agent handed off to Multiply Agent ### (Multiply Agent) 1: Agent Multiply Agent started ### (Multiply Agent) 2: Agent Multiply Agent started tool multiply_by_two ### (Multiply Agent) 3: Agent Multiply Agent ended tool multiply_by_two with result 74 -### (Multiply Agent) 4: Agent Multiply Agent started -### (Multiply Agent) 5: Agent Multiply Agent ended with output number=74 +### (Multiply Agent) 4: Agent Multiply Agent ended with output number=74 Done! """ diff --git a/examples/basic/lifecycle_example.py b/examples/basic/lifecycle_example.py index 285bfecd6..02ce449f4 100644 --- a/examples/basic/lifecycle_example.py +++ b/examples/basic/lifecycle_example.py @@ -105,14 +105,12 @@ async def main() -> None: Enter a max number: 250 ### 1: Agent Start Agent started. Usage: 0 requests, 0 input tokens, 0 output tokens, 0 total tokens ### 2: Tool random_number started. Usage: 1 requests, 148 input tokens, 15 output tokens, 163 total tokens -### 3: Tool random_number ended with result 101. Usage: 1 requests, 148 input tokens, 15 output tokens, 163 total tokens -### 4: Agent Start Agent started. Usage: 1 requests, 148 input tokens, 15 output tokens, 163 total tokens -### 5: Handoff from Start Agent to Multiply Agent. Usage: 2 requests, 323 input tokens, 30 output tokens, 353 total tokens -### 6: Agent Multiply Agent started. Usage: 2 requests, 323 input tokens, 30 output tokens, 353 total tokens -### 7: Tool multiply_by_two started. Usage: 3 requests, 504 input tokens, 46 output tokens, 550 total tokens -### 8: Tool multiply_by_two ended with result 202. Usage: 3 requests, 504 input tokens, 46 output tokens, 550 total tokens -### 9: Agent Multiply Agent started. Usage: 3 requests, 504 input tokens, 46 output tokens, 550 total tokens -### 10: Agent Multiply Agent ended with output number=202. Usage: 4 requests, 714 input tokens, 63 output tokens, 777 total tokens +### 3: Tool random_number ended with result 101. Usage: 1 requests, 148 input tokens, 15 output tokens, 163 total token +### 4: Handoff from Start Agent to Multiply Agent. Usage: 2 requests, 323 input tokens, 30 output tokens, 353 total tokens +### 5: Agent Multiply Agent started. Usage: 2 requests, 323 input tokens, 30 output tokens, 353 total tokens +### 6: Tool multiply_by_two started. Usage: 3 requests, 504 input tokens, 46 output tokens, 550 total tokens +### 7: Tool multiply_by_two ended with result 202. Usage: 3 requests, 504 input tokens, 46 output tokens, 550 total tokens +### 8: Agent Multiply Agent ended with output number=202. Usage: 4 requests, 714 input tokens, 63 output tokens, 777 total tokens Done! """ From d1d2ecca53d1abdd1935aea4922a829908641859 Mon Sep 17 00:00:00 2001 From: Thein Oo Date: Tue, 8 Jul 2025 11:15:58 -0400 Subject: [PATCH 3/9] Support mcp prompts (#1010) ### Summary Add MCP prompt support to enable user-controlled agent instruction generation. This enhancement allows MCP servers to provide prompts that can be used to dynamically generate agent instructions, enabling more flexible and user-controlled agent behavior. **Key changes:** - Added abstract `list_prompts()` and `get_prompt()` methods to base `MCPServer` class - Implemented prompt support in `MCPServerStdio` and `MCPServerStreamableHttp` classes - Added comprehensive test suite for prompt functionality - Created example MCP prompt server with working demonstration - Updated documentation with prompt usage examples **Note:** This PR implements MCP prompt support only. Resource support is not included in this implementation. ### Test plan - **Unit tests**: Added 11 comprehensive tests in `tests/mcp/test_prompt_server.py` covering: - Prompt listing and retrieval - Argument formatting and validation - Agent integration with prompt-generated instructions - Streaming and non-streaming scenarios - Error handling for missing prompts - **Integration tests**: Updated existing MCP test suite to handle new abstract methods - **Example verification**: Created working example with MCP prompt server and client - **All tests pass**: 450/450 tests passing after adding optional dependencies ### Issue number Partially addresses #544 (prompts only, resources not implemented) ### Checks - [x] I've added new tests (if relevant) - [x] I've added/updated the relevant documentation - [x] I've run `make lint` and `make format` - [x] I've made sure tests pass --------- Co-authored-by: thein --- docs/mcp.md | 34 ++- examples/mcp/prompt_server/README.md | 29 +++ examples/mcp/prompt_server/main.py | 110 ++++++++++ examples/mcp/prompt_server/server.py | 37 ++++ src/agents/mcp/server.py | 38 +++- tests/mcp/helpers.py | 14 +- tests/mcp/test_prompt_server.py | 301 +++++++++++++++++++++++++++ 7 files changed, 557 insertions(+), 6 deletions(-) create mode 100644 examples/mcp/prompt_server/README.md create mode 100644 examples/mcp/prompt_server/main.py create mode 100644 examples/mcp/prompt_server/server.py create mode 100644 tests/mcp/test_prompt_server.py diff --git a/docs/mcp.md b/docs/mcp.md index d30a916ac..eef61a047 100644 --- a/docs/mcp.md +++ b/docs/mcp.md @@ -4,7 +4,7 @@ The [Model context protocol](https://modelcontextprotocol.io/introduction) (aka > MCP is an open protocol that standardizes how applications provide context to LLMs. Think of MCP like a USB-C port for AI applications. Just as USB-C provides a standardized way to connect your devices to various peripherals and accessories, MCP provides a standardized way to connect AI models to different data sources and tools. -The Agents SDK has support for MCP. This enables you to use a wide range of MCP servers to provide tools to your Agents. +The Agents SDK has support for MCP. This enables you to use a wide range of MCP servers to provide tools and prompts to your Agents. ## MCP servers @@ -135,6 +135,38 @@ The `ToolFilterContext` provides access to: - `agent`: The agent requesting the tools - `server_name`: The name of the MCP server +## Prompts + +MCP servers can also provide prompts that can be used to dynamically generate agent instructions. This allows you to create reusable instruction templates that can be customized with parameters. + +### Using prompts + +MCP servers that support prompts provide two key methods: + +- `list_prompts()`: Lists all available prompts on the server +- `get_prompt(name, arguments)`: Gets a specific prompt with optional parameters + +```python +# List available prompts +prompts_result = await server.list_prompts() +for prompt in prompts_result.prompts: + print(f"Prompt: {prompt.name} - {prompt.description}") + +# Get a specific prompt with parameters +prompt_result = await server.get_prompt( + "generate_code_review_instructions", + {"focus": "security vulnerabilities", "language": "python"} +) +instructions = prompt_result.messages[0].content.text + +# Use the prompt-generated instructions with an Agent +agent = Agent( + name="Code Reviewer", + instructions=instructions, # Instructions from MCP prompt + mcp_servers=[server] +) +``` + ## 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 [`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. diff --git a/examples/mcp/prompt_server/README.md b/examples/mcp/prompt_server/README.md new file mode 100644 index 000000000..c1b1c3b37 --- /dev/null +++ b/examples/mcp/prompt_server/README.md @@ -0,0 +1,29 @@ +# MCP Prompt Server Example + +This example uses a local MCP prompt server in [server.py](server.py). + +Run the example via: + +``` +uv run python examples/mcp/prompt_server/main.py +``` + +## Details + +The example uses the `MCPServerStreamableHttp` class from `agents.mcp`. The server runs in a sub-process at `http://localhost:8000/mcp` and provides user-controlled prompts that generate agent instructions. + +The server exposes prompts like `generate_code_review_instructions` that take parameters such as focus area and programming language. The agent calls these prompts to dynamically generate its system instructions based on user-provided parameters. + +## Workflow + +The example demonstrates two key functions: + +1. **`show_available_prompts`** - Lists all available prompts on the MCP server, showing users what prompts they can select from. This demonstrates the discovery aspect of MCP prompts. + +2. **`demo_code_review`** - Shows the complete user-controlled prompt workflow: + - Calls `generate_code_review_instructions` with specific parameters (focus: "security vulnerabilities", language: "python") + - Uses the generated instructions to create an Agent with specialized code review capabilities + - Runs the agent against vulnerable sample code (command injection via `os.system`) + - The agent analyzes the code and provides security-focused feedback using available tools + +This pattern allows users to dynamically configure agent behavior through MCP prompts rather than hardcoded instructions. \ No newline at end of file diff --git a/examples/mcp/prompt_server/main.py b/examples/mcp/prompt_server/main.py new file mode 100644 index 000000000..8f2991fc0 --- /dev/null +++ b/examples/mcp/prompt_server/main.py @@ -0,0 +1,110 @@ +import asyncio +import os +import shutil +import subprocess +import time +from typing import Any + +from agents import Agent, Runner, gen_trace_id, trace +from agents.mcp import MCPServer, MCPServerStreamableHttp +from agents.model_settings import ModelSettings + + +async def get_instructions_from_prompt(mcp_server: MCPServer, prompt_name: str, **kwargs) -> str: + """Get agent instructions by calling MCP prompt endpoint (user-controlled)""" + print(f"Getting instructions from prompt: {prompt_name}") + + try: + prompt_result = await mcp_server.get_prompt(prompt_name, kwargs) + content = prompt_result.messages[0].content + if hasattr(content, 'text'): + instructions = content.text + else: + instructions = str(content) + print("Generated instructions") + return instructions + except Exception as e: + print(f"Failed to get instructions: {e}") + return f"You are a helpful assistant. Error: {e}" + + +async def demo_code_review(mcp_server: MCPServer): + """Demo: Code review with user-selected prompt""" + print("=== CODE REVIEW DEMO ===") + + # User explicitly selects prompt and parameters + instructions = await get_instructions_from_prompt( + mcp_server, + "generate_code_review_instructions", + focus="security vulnerabilities", + language="python", + ) + + agent = Agent( + name="Code Reviewer Agent", + instructions=instructions, # Instructions from MCP prompt + model_settings=ModelSettings(tool_choice="auto"), + ) + + message = """Please review this code: + +def process_user_input(user_input): + command = f"echo {user_input}" + os.system(command) + return "Command executed" + +""" + + print(f"Running: {message[:60]}...") + result = await Runner.run(starting_agent=agent, input=message) + print(result.final_output) + print("\n" + "=" * 50 + "\n") + + +async def show_available_prompts(mcp_server: MCPServer): + """Show available prompts for user selection""" + print("=== AVAILABLE PROMPTS ===") + + prompts_result = await mcp_server.list_prompts() + print("User can select from these prompts:") + for i, prompt in enumerate(prompts_result.prompts, 1): + print(f" {i}. {prompt.name} - {prompt.description}") + print() + + +async def main(): + async with MCPServerStreamableHttp( + name="Simple Prompt Server", + params={"url": "http://localhost:8000/mcp"}, + ) as server: + trace_id = gen_trace_id() + with trace(workflow_name="Simple Prompt Demo", trace_id=trace_id): + print(f"Trace: https://platform.openai.com/traces/trace?trace_id={trace_id}\n") + + await show_available_prompts(server) + await demo_code_review(server) + + +if __name__ == "__main__": + if not shutil.which("uv"): + raise RuntimeError("uv is not installed") + + process: subprocess.Popen[Any] | None = None + try: + this_dir = os.path.dirname(os.path.abspath(__file__)) + server_file = os.path.join(this_dir, "server.py") + + print("Starting Simple Prompt Server...") + process = subprocess.Popen(["uv", "run", server_file]) + time.sleep(3) + print("Server started\n") + except Exception as e: + print(f"Error starting server: {e}") + exit(1) + + try: + asyncio.run(main()) + finally: + if process: + process.terminate() + print("Server terminated.") diff --git a/examples/mcp/prompt_server/server.py b/examples/mcp/prompt_server/server.py new file mode 100644 index 000000000..01dcbac34 --- /dev/null +++ b/examples/mcp/prompt_server/server.py @@ -0,0 +1,37 @@ +from mcp.server.fastmcp import FastMCP + +# Create server +mcp = FastMCP("Prompt Server") + + +# Instruction-generating prompts (user-controlled) +@mcp.prompt() +def generate_code_review_instructions( + focus: str = "general code quality", language: str = "python" +) -> str: + """Generate agent instructions for code review tasks""" + print(f"[debug-server] generate_code_review_instructions({focus}, {language})") + + return f"""You are a senior {language} code review specialist. Your role is to provide comprehensive code analysis with focus on {focus}. + +INSTRUCTIONS: +- Analyze code for quality, security, performance, and best practices +- Provide specific, actionable feedback with examples +- Identify potential bugs, vulnerabilities, and optimization opportunities +- Suggest improvements with code examples when applicable +- Be constructive and educational in your feedback +- Focus particularly on {focus} aspects + +RESPONSE FORMAT: +1. Overall Assessment +2. Specific Issues Found +3. Security Considerations +4. Performance Notes +5. Recommended Improvements +6. Best Practices Suggestions + +Use the available tools to check current time if you need timestamps for your analysis.""" + + +if __name__ == "__main__": + mcp.run(transport="streamable-http") diff --git a/src/agents/mcp/server.py b/src/agents/mcp/server.py index f6c2b58ef..b7e41c91d 100644 --- a/src/agents/mcp/server.py +++ b/src/agents/mcp/server.py @@ -13,7 +13,7 @@ from mcp.client.sse import sse_client from mcp.client.streamable_http import GetSessionIdCallback, streamablehttp_client from mcp.shared.message import SessionMessage -from mcp.types import CallToolResult, InitializeResult +from mcp.types import CallToolResult, GetPromptResult, InitializeResult, ListPromptsResult from typing_extensions import NotRequired, TypedDict from ..exceptions import UserError @@ -63,6 +63,20 @@ async def call_tool(self, tool_name: str, arguments: dict[str, Any] | None) -> C """Invoke a tool on the server.""" pass + @abc.abstractmethod + async def list_prompts( + self, + ) -> ListPromptsResult: + """List the prompts available on the server.""" + pass + + @abc.abstractmethod + async def get_prompt( + self, name: str, arguments: dict[str, Any] | None = None + ) -> GetPromptResult: + """Get a specific prompt from the server.""" + pass + class _MCPServerWithClientSession(MCPServer, abc.ABC): """Base class for MCP servers that use a `ClientSession` to communicate with the server.""" @@ -118,9 +132,7 @@ async def _apply_tool_filter( return await self._apply_dynamic_tool_filter(tools, run_context, agent) def _apply_static_tool_filter( - self, - tools: list[MCPTool], - static_filter: ToolFilterStatic + self, tools: list[MCPTool], static_filter: ToolFilterStatic ) -> list[MCPTool]: """Apply static tool filtering based on allowlist and blocklist.""" filtered_tools = tools @@ -261,6 +273,24 @@ async def call_tool(self, tool_name: str, arguments: dict[str, Any] | None) -> C return await self.session.call_tool(tool_name, arguments) + async def list_prompts( + self, + ) -> ListPromptsResult: + """List the prompts available on the server.""" + if not self.session: + raise UserError("Server not initialized. Make sure you call `connect()` first.") + + return await self.session.list_prompts() + + async def get_prompt( + self, name: str, arguments: dict[str, Any] | None = None + ) -> GetPromptResult: + """Get a specific prompt from the server.""" + if not self.session: + raise UserError("Server not initialized. Make sure you call `connect()` first.") + + return await self.session.get_prompt(name, arguments) + async def cleanup(self): """Cleanup the server.""" async with self._cleanup_lock: diff --git a/tests/mcp/helpers.py b/tests/mcp/helpers.py index e0d8a813d..31d43c228 100644 --- a/tests/mcp/helpers.py +++ b/tests/mcp/helpers.py @@ -4,7 +4,7 @@ from typing import Any from mcp import Tool as MCPTool -from mcp.types import CallToolResult, TextContent +from mcp.types import CallToolResult, GetPromptResult, ListPromptsResult, PromptMessage, TextContent from agents.mcp import MCPServer from agents.mcp.server import _MCPServerWithClientSession @@ -94,6 +94,18 @@ async def call_tool(self, tool_name: str, arguments: dict[str, Any] | None) -> C content=[TextContent(text=self.tool_results[-1], type="text")], ) + async def list_prompts(self, run_context=None, agent=None) -> ListPromptsResult: + """Return empty list of prompts for fake server""" + return ListPromptsResult(prompts=[]) + + async def get_prompt( + self, name: str, arguments: dict[str, Any] | None = None + ) -> GetPromptResult: + """Return a simple prompt result for fake server""" + content = f"Fake prompt content for {name}" + message = PromptMessage(role="user", content=TextContent(type="text", text=content)) + return GetPromptResult(description=f"Fake prompt: {name}", messages=[message]) + @property def name(self) -> str: return self._server_name diff --git a/tests/mcp/test_prompt_server.py b/tests/mcp/test_prompt_server.py new file mode 100644 index 000000000..15afe28e4 --- /dev/null +++ b/tests/mcp/test_prompt_server.py @@ -0,0 +1,301 @@ +from typing import Any + +import pytest + +from agents import Agent, Runner +from agents.mcp import MCPServer + +from ..fake_model import FakeModel +from ..test_responses import get_text_message + + +class FakeMCPPromptServer(MCPServer): + """Fake MCP server for testing prompt functionality""" + + def __init__(self, server_name: str = "fake_prompt_server"): + self.prompts: list[Any] = [] + self.prompt_results: dict[str, str] = {} + self._server_name = server_name + + def add_prompt(self, name: str, description: str, arguments: dict[str, Any] | None = None): + """Add a prompt to the fake server""" + from mcp.types import Prompt + + prompt = Prompt(name=name, description=description, arguments=[]) + self.prompts.append(prompt) + + def set_prompt_result(self, name: str, result: str): + """Set the result that should be returned for a prompt""" + self.prompt_results[name] = result + + async def connect(self): + pass + + async def cleanup(self): + pass + + async def list_prompts(self, run_context=None, agent=None): + """List available prompts""" + from mcp.types import ListPromptsResult + + return ListPromptsResult(prompts=self.prompts) + + async def get_prompt(self, name: str, arguments: dict[str, Any] | None = None): + """Get a prompt with arguments""" + from mcp.types import GetPromptResult, PromptMessage, TextContent + + if name not in self.prompt_results: + raise ValueError(f"Prompt '{name}' not found") + + content = self.prompt_results[name] + + # If it's a format string, try to format it with arguments + if arguments and "{" in content: + try: + content = content.format(**arguments) + except KeyError: + pass # Use original content if formatting fails + + message = PromptMessage(role="user", content=TextContent(type="text", text=content)) + + return GetPromptResult(description=f"Generated prompt for {name}", messages=[message]) + + async def list_tools(self, run_context=None, agent=None): + return [] + + async def call_tool(self, tool_name: str, arguments: dict[str, Any] | None = None): + raise NotImplementedError("This fake server doesn't support tools") + + @property + def name(self) -> str: + return self._server_name + + +@pytest.mark.asyncio +async def test_list_prompts(): + """Test listing available prompts""" + server = FakeMCPPromptServer() + server.add_prompt( + "generate_code_review_instructions", "Generate agent instructions for code review tasks" + ) + + result = await server.list_prompts() + + assert len(result.prompts) == 1 + assert result.prompts[0].name == "generate_code_review_instructions" + assert "code review" in result.prompts[0].description + + +@pytest.mark.asyncio +async def test_get_prompt_without_arguments(): + """Test getting a prompt without arguments""" + server = FakeMCPPromptServer() + server.add_prompt("simple_prompt", "A simple prompt") + server.set_prompt_result("simple_prompt", "You are a helpful assistant.") + + result = await server.get_prompt("simple_prompt") + + assert len(result.messages) == 1 + assert result.messages[0].content.text == "You are a helpful assistant." + + +@pytest.mark.asyncio +async def test_get_prompt_with_arguments(): + """Test getting a prompt with arguments""" + server = FakeMCPPromptServer() + server.add_prompt( + "generate_code_review_instructions", "Generate agent instructions for code review tasks" + ) + server.set_prompt_result( + "generate_code_review_instructions", + "You are a senior {language} code review specialist. Focus on {focus}.", + ) + + result = await server.get_prompt( + "generate_code_review_instructions", + {"focus": "security vulnerabilities", "language": "python"}, + ) + + assert len(result.messages) == 1 + expected_text = ( + "You are a senior python code review specialist. Focus on security vulnerabilities." + ) + assert result.messages[0].content.text == expected_text + + +@pytest.mark.asyncio +async def test_get_prompt_not_found(): + """Test getting a prompt that doesn't exist""" + server = FakeMCPPromptServer() + + with pytest.raises(ValueError, match="Prompt 'nonexistent' not found"): + await server.get_prompt("nonexistent") + + +@pytest.mark.asyncio +async def test_agent_with_prompt_instructions(): + """Test using prompt-generated instructions with an agent""" + server = FakeMCPPromptServer() + server.add_prompt( + "generate_code_review_instructions", "Generate agent instructions for code review tasks" + ) + server.set_prompt_result( + "generate_code_review_instructions", + "You are a code reviewer. Analyze the provided code for security issues.", + ) + + # Get instructions from prompt + prompt_result = await server.get_prompt("generate_code_review_instructions") + instructions = prompt_result.messages[0].content.text + + # Create agent with prompt-generated instructions + model = FakeModel() + agent = Agent(name="prompt_agent", instructions=instructions, model=model, mcp_servers=[server]) + + # Mock model response + model.add_multiple_turn_outputs( + [[get_text_message("Code analysis complete. Found security vulnerability.")]] + ) + + # Run the agent + result = await Runner.run(agent, input="Review this code: def unsafe_exec(cmd): os.system(cmd)") + + assert "Code analysis complete" in result.final_output + assert ( + agent.instructions + == "You are a code reviewer. Analyze the provided code for security issues." + ) + + +@pytest.mark.asyncio +@pytest.mark.parametrize("streaming", [False, True]) +async def test_agent_with_prompt_instructions_streaming(streaming: bool): + """Test using prompt-generated instructions with streaming and non-streaming""" + server = FakeMCPPromptServer() + server.add_prompt( + "generate_code_review_instructions", "Generate agent instructions for code review tasks" + ) + server.set_prompt_result( + "generate_code_review_instructions", + "You are a {language} code reviewer focusing on {focus}.", + ) + + # Get instructions from prompt with arguments + prompt_result = await server.get_prompt( + "generate_code_review_instructions", {"language": "Python", "focus": "security"} + ) + instructions = prompt_result.messages[0].content.text + + # Create agent + model = FakeModel() + agent = Agent( + name="streaming_prompt_agent", instructions=instructions, model=model, mcp_servers=[server] + ) + + model.add_multiple_turn_outputs([[get_text_message("Security analysis complete.")]]) + + if streaming: + streaming_result = Runner.run_streamed(agent, input="Review code") + async for _ in streaming_result.stream_events(): + pass + final_result = streaming_result.final_output + else: + result = await Runner.run(agent, input="Review code") + final_result = result.final_output + + assert "Security analysis complete" in final_result + assert agent.instructions == "You are a Python code reviewer focusing on security." + + +@pytest.mark.asyncio +async def test_multiple_prompts(): + """Test server with multiple prompts""" + server = FakeMCPPromptServer() + + # Add multiple prompts + server.add_prompt( + "generate_code_review_instructions", "Generate agent instructions for code review tasks" + ) + server.add_prompt( + "generate_testing_instructions", "Generate agent instructions for testing tasks" + ) + + server.set_prompt_result("generate_code_review_instructions", "You are a code reviewer.") + server.set_prompt_result("generate_testing_instructions", "You are a test engineer.") + + # Test listing prompts + prompts_result = await server.list_prompts() + assert len(prompts_result.prompts) == 2 + + prompt_names = [p.name for p in prompts_result.prompts] + assert "generate_code_review_instructions" in prompt_names + assert "generate_testing_instructions" in prompt_names + + # Test getting each prompt + review_result = await server.get_prompt("generate_code_review_instructions") + assert review_result.messages[0].content.text == "You are a code reviewer." + + testing_result = await server.get_prompt("generate_testing_instructions") + assert testing_result.messages[0].content.text == "You are a test engineer." + + +@pytest.mark.asyncio +async def test_prompt_with_complex_arguments(): + """Test prompt with complex argument formatting""" + server = FakeMCPPromptServer() + server.add_prompt( + "generate_detailed_instructions", "Generate detailed instructions with multiple parameters" + ) + server.set_prompt_result( + "generate_detailed_instructions", + "You are a {role} specialist. Your focus is on {focus}. " + + "You work with {language} code. Your experience level is {level}.", + ) + + arguments = { + "role": "security", + "focus": "vulnerability detection", + "language": "Python", + "level": "senior", + } + + result = await server.get_prompt("generate_detailed_instructions", arguments) + + expected = ( + "You are a security specialist. Your focus is on vulnerability detection. " + "You work with Python code. Your experience level is senior." + ) + assert result.messages[0].content.text == expected + + +@pytest.mark.asyncio +async def test_prompt_with_missing_arguments(): + """Test prompt with missing arguments in format string""" + server = FakeMCPPromptServer() + server.add_prompt("incomplete_prompt", "Prompt with missing arguments") + server.set_prompt_result("incomplete_prompt", "You are a {role} working on {task}.") + + # Only provide one of the required arguments + result = await server.get_prompt("incomplete_prompt", {"role": "developer"}) + + # Should return the original string since formatting fails + assert result.messages[0].content.text == "You are a {role} working on {task}." + + +@pytest.mark.asyncio +async def test_prompt_server_cleanup(): + """Test that prompt server cleanup works correctly""" + server = FakeMCPPromptServer() + server.add_prompt("test_prompt", "Test prompt") + server.set_prompt_result("test_prompt", "Test result") + + # Test that server works before cleanup + result = await server.get_prompt("test_prompt") + assert result.messages[0].content.text == "Test result" + + # Cleanup should not raise any errors + await server.cleanup() + + # Server should still work after cleanup (in this fake implementation) + result = await server.get_prompt("test_prompt") + assert result.messages[0].content.text == "Test result" From e5ba91ba04b2d31a1c0a9db55b3b3c9c42c23d61 Mon Sep 17 00:00:00 2001 From: Viraj <123119434+vrtnis@users.noreply.github.com> Date: Tue, 8 Jul 2025 10:22:27 -0700 Subject: [PATCH 4/9] Add on_start support to VoiceWorkflowBase and VoicePipeline (#922) I added an optional `on_start()` method to `VoiceWorkflowBase`, allowing voice workflows to emit an initial TTS message before any user input. This aligns with the usage pattern suggested in #488 The `VoicePipeline._run_multi_turn()` method was updated to call this hook and stream any yielded messages via TTS before transcription begins. No changes are required to existing workflows, as the method defaults to returning an empty `AsyncIterator[str]`. Resolves #488 and thus improves UX for voice agents that need to greet or instruct users proactively. All tests pass under Python 3.12. Let me know if you'd like an example workflow or docs added in a follow-up! --- src/agents/voice/pipeline.py | 6 ++++++ src/agents/voice/workflow.py | 8 ++++++++ 2 files changed, 14 insertions(+) diff --git a/src/agents/voice/pipeline.py b/src/agents/voice/pipeline.py index d1dac57cf..5addd995f 100644 --- a/src/agents/voice/pipeline.py +++ b/src/agents/voice/pipeline.py @@ -125,6 +125,12 @@ async def _run_multi_turn(self, audio_input: StreamedAudioInput) -> StreamedAudi self._get_tts_model(), self.config.tts_settings, self.config ) + try: + async for intro_text in self.workflow.on_start(): + await output._add_text(intro_text) + except Exception as e: + logger.warning(f"on_start() failed: {e}") + transcription_session = await self._get_stt_model().create_session( audio_input, self.config.stt_settings, diff --git a/src/agents/voice/workflow.py b/src/agents/voice/workflow.py index c706ec413..538676ad1 100644 --- a/src/agents/voice/workflow.py +++ b/src/agents/voice/workflow.py @@ -32,6 +32,14 @@ def run(self, transcription: str) -> AsyncIterator[str]: """ pass + async def on_start(self) -> AsyncIterator[str]: + """ + Optional method that runs before any user input is received. Can be used + to deliver a greeting or instruction via TTS. Defaults to doing nothing. + """ + return + yield + class VoiceWorkflowHelper: @classmethod From 6358cd9525134ca3347085de654a33f9ca480690 Mon Sep 17 00:00:00 2001 From: Antoine Legrand <2t.antoine@gmail.com> Date: Tue, 8 Jul 2025 19:22:56 +0200 Subject: [PATCH 5/9] Add Makefile check rule to run all the linters and checkers (#1038) It adds a Makefile rule `check` to run all linters and checkers in a single command. With only `make check` instead of 3-4 commands, it can help to forget one of them before pushing a PR. --- Makefile | 8 ++++++-- README.md | 6 ++++++ 2 files changed, 12 insertions(+), 2 deletions(-) diff --git a/Makefile b/Makefile index 5c6aba425..9a88f93a1 100644 --- a/Makefile +++ b/Makefile @@ -7,6 +7,10 @@ format: uv run ruff format uv run ruff check --fix +.PHONY: format-check +format-check: + uv run ruff format --check + .PHONY: lint lint: uv run ruff check @@ -55,5 +59,5 @@ serve-docs: deploy-docs: uv run mkdocs gh-deploy --force --verbose - - +.PHONY: check +check: format-check lint mypy tests diff --git a/README.md b/README.md index 079aebb06..755c342ae 100644 --- a/README.md +++ b/README.md @@ -170,10 +170,16 @@ make sync 2. (After making changes) lint/test +``` +make check # run tests linter and typechecker +``` + +Or to run them individually: ``` make tests # run tests make mypy # run typechecker make lint # run linter +make format-check # run style checker ``` ## Acknowledgements From 1720e4a8bc895c33409594732db1dad7c02d9027 Mon Sep 17 00:00:00 2001 From: Antoine Legrand <2t.antoine@gmail.com> Date: Tue, 8 Jul 2025 19:23:09 +0200 Subject: [PATCH 6/9] Support for file_input content (#fix 893) (#1009) PDF and file upload are supported by litellm and various models. This PR enables them. fixes #893 --- src/agents/models/chatcmpl_converter.py | 16 +++++++++++++++- 1 file changed, 15 insertions(+), 1 deletion(-) diff --git a/src/agents/models/chatcmpl_converter.py b/src/agents/models/chatcmpl_converter.py index 25d9f083d..9d0c6cf5e 100644 --- a/src/agents/models/chatcmpl_converter.py +++ b/src/agents/models/chatcmpl_converter.py @@ -19,6 +19,7 @@ ChatCompletionToolMessageParam, ChatCompletionUserMessageParam, ) +from openai.types.chat.chat_completion_content_part_param import File, FileFile from openai.types.chat.chat_completion_tool_param import ChatCompletionToolParam from openai.types.chat.completion_create_params import ResponseFormat from openai.types.responses import ( @@ -27,6 +28,7 @@ ResponseFunctionToolCall, ResponseFunctionToolCallParam, ResponseInputContentParam, + ResponseInputFileParam, ResponseInputImageParam, ResponseInputTextParam, ResponseOutputMessage, @@ -251,7 +253,19 @@ def extract_all_content( ) ) elif isinstance(c, dict) and c.get("type") == "input_file": - raise UserError(f"File uploads are not supported for chat completions {c}") + casted_file_param = cast(ResponseInputFileParam, c) + if "file_data" not in casted_file_param or not casted_file_param["file_data"]: + raise UserError( + f"Only file_data is supported for input_file {casted_file_param}" + ) + out.append( + File( + type="file", + file=FileFile( + file_data=casted_file_param["file_data"], + ), + ) + ) else: raise UserError(f"Unknown content: {c}") return out From e251fa6b1b726a4d8261a8573edd7e134d518680 Mon Sep 17 00:00:00 2001 From: Muhammad Fasih <161964251+HafizFasih@users.noreply.github.com> Date: Tue, 8 Jul 2025 22:25:31 +0500 Subject: [PATCH 7/9] description_override is not properly used for function_schema.description (#1000) Describe the bug A clear and concise description of what the bug is. In the function_schema method of the OpenAI Agents SDK, the following line: ```python description=description_override or doc_info.description if doc_info else None ``` does not honor description_override when `use_docstring_info=False`. This happens because of operator precedence in Python. Without parentheses, the expression is interpreted as: ```python description=(description_override or doc_info.description) if doc_info else None ``` So when doc_info is None, even if description_override is set, it falls back to None Debug information Python version (e.g. Python 3.10) Repro steps ```python from agents.function_schema import function_schema def my_func(): pass schema = function_schema( my_func, description_override ="CustomDescription", use_docstring_info=False ) print(schema.description) # Expected: "CustomDescription", Actual: None ``` Expected behavior Even when use_docstring_info=False, if description_override is provided, it should be used for description. Suggested Fix: Update this line: description=description_override or doc_info.description if doc_info else None To this (with parentheses to enforce correct evaluation): description=description_override or (doc_info.description if doc_info else None) --- src/agents/function_schema.py | 3 ++- 1 file changed, 2 insertions(+), 1 deletion(-) diff --git a/src/agents/function_schema.py b/src/agents/function_schema.py index dd1db1fee..e1a91e189 100644 --- a/src/agents/function_schema.py +++ b/src/agents/function_schema.py @@ -337,7 +337,8 @@ def function_schema( # 5. Return as a FuncSchema dataclass return FuncSchema( name=func_name, - description=description_override or doc_info.description if doc_info else None, + # Ensure description_override takes precedence even if docstring info is disabled. + description=description_override or (doc_info.description if doc_info else None), params_pydantic_model=dynamic_model, params_json_schema=json_schema, signature=sig, From c92fe77e832da77642e9fb81db4721a1c06a8d69 Mon Sep 17 00:00:00 2001 From: "Zhanzhao (Deo) Liang" Date: Wed, 9 Jul 2025 01:26:23 +0800 Subject: [PATCH 8/9] avoid concat tool call delta id (#990) --- src/agents/models/chatcmpl_stream_handler.py | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/src/agents/models/chatcmpl_stream_handler.py b/src/agents/models/chatcmpl_stream_handler.py index 0cf1e6a3e..83fa32abc 100644 --- a/src/agents/models/chatcmpl_stream_handler.py +++ b/src/agents/models/chatcmpl_stream_handler.py @@ -276,7 +276,7 @@ async def handle_stream( state.function_calls[tc_delta.index].name += ( tc_function.name if tc_function else "" ) or "" - state.function_calls[tc_delta.index].call_id += tc_delta.id or "" + state.function_calls[tc_delta.index].call_id = tc_delta.id or "" if state.reasoning_content_index_and_output: yield ResponseReasoningSummaryPartDoneEvent( From db85a6d0310de3bb608555ee6b43bc9579e26e0c Mon Sep 17 00:00:00 2001 From: Nathan Brake <33383515+njbrake@users.noreply.github.com> Date: Tue, 8 Jul 2025 13:28:16 -0400 Subject: [PATCH 9/9] Fix #976 MCP filtering, make agent and run ctx optional (#977) This is a patch to address the most pressing issue of #976 while we discuss whether or not these parameters should exist in `list_tools` or should be migrated elsewhere. Resolves #976 --- src/agents/mcp/server.py | 10 ++++++---- 1 file changed, 6 insertions(+), 4 deletions(-) diff --git a/src/agents/mcp/server.py b/src/agents/mcp/server.py index b7e41c91d..4fd606e34 100644 --- a/src/agents/mcp/server.py +++ b/src/agents/mcp/server.py @@ -52,8 +52,8 @@ async def cleanup(self): @abc.abstractmethod async def list_tools( self, - run_context: RunContextWrapper[Any], - agent: Agent[Any], + run_context: RunContextWrapper[Any] | None = None, + agent: Agent[Any] | None = None, ) -> list[MCPTool]: """List the tools available on the server.""" pass @@ -243,8 +243,8 @@ async def connect(self): async def list_tools( self, - run_context: RunContextWrapper[Any], - agent: Agent[Any], + run_context: RunContextWrapper[Any] | None = None, + agent: Agent[Any] | None = None, ) -> list[MCPTool]: """List the tools available on the server.""" if not self.session: @@ -263,6 +263,8 @@ async def list_tools( # Filter tools based on tool_filter filtered_tools = tools if self.tool_filter is not None: + if run_context is None or agent is None: + raise UserError("run_context and agent are required for dynamic tool filtering") filtered_tools = await self._apply_tool_filter(filtered_tools, run_context, agent) return filtered_tools