From 2c8df11e2332679d53a26e4fbfc1182a286c7d0e Mon Sep 17 00:00:00 2001 From: Mark Stuart Date: Fri, 20 Nov 2026 21:32:29 -0800 Subject: [PATCH 1/2] Show how to limit function and MCP tool output and retrieve the original --- examples/mcp/bounded_tool_output/README.md | 33 +++ examples/mcp/bounded_tool_output/main.py | 182 +++++++++++++++ examples/mcp/bounded_tool_output/server.py | 66 ++++++ tests/mcp/test_bounded_tool_output_example.py | 217 ++++++++++++++++++ 4 files changed, 498 insertions(+) create mode 100644 examples/mcp/bounded_tool_output/README.md create mode 100644 examples/mcp/bounded_tool_output/main.py create mode 100644 examples/mcp/bounded_tool_output/server.py create mode 100644 tests/mcp/test_bounded_tool_output_example.py diff --git a/examples/mcp/bounded_tool_output/README.md b/examples/mcp/bounded_tool_output/README.md new file mode 100644 index 0000000000..7207bd209b --- /dev/null +++ b/examples/mcp/bounded_tool_output/README.md @@ -0,0 +1,33 @@ +# Keep large tool results out of the conversation + +Run the example from this source checkout. It uses a scripted model and a local MCP server over stdio. No API key is needed. + +```sh +uv run python examples/mcp/bounded_tool_output/main.py +``` + +Both inspection reports exceed the example's 128-byte text budget. The next model request, SDK history and caller receive warning counts of 20 and 8 with random references. The application fetches a page of each original report without adding it to the conversation. + +## Choose what to share + +[main.py](main.py) uses two routes. + +- For the local `inspect_site` function, the SDK awaits the operation. Then `ToolExecutionConfig.prepare_tool_output` checks that the result is a string and applies the budget. +- For SDK-discovered MCP tools, `ReportServer.call_tool` awaits the peer and selects successful `read.report` calls on the configured `Inspection reports` server. At this point the wrapper can still check `isError` and see every block. It replaces large reports before SDK conversion, custom data extraction and function span output capture. + +For a nonempty structured object, the wrapper uses its JSON in place of the fallback text. It resolves the sample `{"ticket": "site"}` by awaiting a local report. The SDK calls `authorize_call` with the run context before sending the request. Never let a server pick another user's record or an arbitrary file or URL. + +The budget covers the sum of UTF-8 text bytes per result, including the reference. Smaller reports pass through in full. For large reports, the summary shares only the count of literal `WARN:` markers. Choose facts safe to disclose for your data. The first text slot holds the replacement and the other text slots stay empty. A structured result without a text slot gets one. + +## Retrieve privately + +Create one `Reports` instance per run. Get the owner and the requester from your application's authentication system. Never accept either identity from tool arguments or a reference. Call `reports.fetch(requester, reference, part=0, offset=0)` in application code. Each page contains up to 64 characters. Advance the offset by the page length, or select another text part. Structured reports have one JSON part. + +The originals stay in process memory outside SDK context. Leaving the `closing` block revokes every reference, including on failure or cancellation. Saved conversations cannot restore the originals. This example has no storage quota or durable store. + +## Limits + +- Selected successes support text and images. Images retain their contents and positions. Other media stop the run. The budget excludes images, block metadata and serialization overhead. Use this policy only for tools that accept a text replacement without a required output schema. +- Unselected results and MCP errors pass through, even when large. Exceptions from selected operations and invalid summaries stop the run. Cancelling the run during preparation withholds the pending output. It cannot undo a remote action or stop counting already underway in a worker thread. +- This example disables tracing. Keep tool-data logging disabled and check logs, exceptions and other observers separately. Small reports, images and errors can still contain sensitive data. +- The recipe covers SDK-executed tools. It excludes native tools and provider-hosted MCP. Editing later requests cannot retract data already received by a provider. diff --git a/examples/mcp/bounded_tool_output/main.py b/examples/mcp/bounded_tool_output/main.py new file mode 100644 index 0000000000..f1de2d7e5b --- /dev/null +++ b/examples/mcp/bounded_tool_output/main.py @@ -0,0 +1,182 @@ +"""Keep large reports out of model input and SDK history. + +Run offline from the checkout with `uv run python examples/mcp/bounded_tool_output/main.py`. +""" + +import asyncio +import json +import secrets +import sys +from contextlib import closing +from pathlib import Path +from typing import Any + +from mcp.types import CallToolResult, ImageContent, TextContent + +from agents import Agent, RunConfig, Runner, ToolCallHookContext, ToolExecutionConfig, UserError +from agents.decorators import tool +from agents.mcp import MCPServerStdio, MCPToolMetaContext +from agents.testing import ScriptedModel, assistant_message, function_call + +MAX_TEXT_BYTES = 128 +SERVER = "Inspection reports" + + +async def site_report() -> str: + """Read the local inspection report.""" + return "WARN: synthetic site detail\n" * 20 + + +@tool(failure_error_function=None) +async def inspect_site() -> str: + """Read the local inspection report.""" + return await site_report() + + +async def summarize(texts: tuple[str, ...]) -> str: + """Share only the number of warning markers in these synthetic reports.""" + count = await asyncio.to_thread(lambda: sum(text.count("WARN:") for text in texts)) + return f"Inspection report with {count} warning markers." + + +class Reports: + """Private storage for one owner and one run. Never put this object in SDK context.""" + + def __init__(self, owner: str): + self._owner = owner + self._texts: dict[str, tuple[str, ...]] | None = {} + + def close(self) -> None: + self._texts = None + + def fetch(self, requester: str, reference: str, *, part: int = 0, offset: int = 0) -> str: + self.authorize(requester) + if self._texts is None or reference not in self._texts: + raise PermissionError("Report unavailable") + if part < 0 or offset < 0: + raise ValueError("Use a nonnegative part and offset") + return self._texts[reference][part][offset : offset + 64] + + def authorize(self, requester: str) -> None: + if self._texts is None or requester != self._owner: + raise PermissionError("Report unavailable") + + async def prepare(self, call: ToolCallHookContext[str], output: Any) -> Any: + if call.tool is not inspect_site: + return output + self.authorize(call.run_context.context) + if not isinstance(output, str): + raise UserError("Expected a report string") + return await self.bound((output,)) or output + + async def bound(self, texts: tuple[str, ...]) -> str | None: + if sum(len(text.encode()) for text in texts) <= MAX_TEXT_BYTES: + return None + + summary = await summarize(texts) + if not isinstance(summary, str) or not summary.strip(): + raise UserError("Expected a nonempty report summary") + reference = secrets.token_urlsafe(24) + replacement = f"{summary} Reference: {reference}" + if len(replacement.encode()) > MAX_TEXT_BYTES: + raise UserError("Report summary exceeds the text budget") + if self._texts is None: + raise RuntimeError("Report storage closed") + self._texts[reference] = texts + return replacement + + +class ReportServer(MCPServerStdio): + """Shape the peer result before the SDK converts, logs or traces it.""" + + def __init__(self, reports: Reports, name: str = SERVER): + self.reports = reports + super().__init__( + name=name, + params={ + "command": sys.executable, + "args": [str(Path(__file__).with_name("server.py"))], + }, + tool_meta_resolver=self.authorize_call, + failure_error_function=None, + ) + + def authorize_call(self, call: MCPToolMetaContext) -> None: + if call.server_name == SERVER and call.tool_name == "read.report": + self.reports.authorize(call.run_context.context) + + async def call_tool( + self, tool_name: str, arguments: dict[str, Any] | None, meta: dict[str, Any] | None = None + ) -> CallToolResult: + result = await super().call_tool(tool_name, arguments, meta=meta) + if self.name != SERVER or tool_name != "read.report": + return result + # Wire aliases are the same in both supported MCP client versions. + fields = result.model_dump(by_alias=True, exclude={"content", "meta"}) + if fields.get("isError"): + return result + if any(not isinstance(block, (TextContent, ImageContent)) for block in result.content): + raise UserError("Unsupported report media") + + structured = fields.get("structuredContent") + if structured: + if structured == {"ticket": "site"}: + structured = {"report": await site_report()} + text = json.dumps(structured) + replacement = await self.reports.bound((text,)) or text + else: + texts = tuple(part.text for part in result.content if isinstance(part, TextContent)) + replacement = await self.reports.bound(texts) + if replacement is None: + return result + + # Start a new result so neither structuredContent nor _meta carries the original. + parts = list(result.content) + slots = [i for i, part in enumerate(parts) if isinstance(part, TextContent)] + if not slots: + parts.append(TextContent(type="text", text=replacement)) + for i in slots: + parts[i] = TextContent(type="text", text=replacement if i == slots[0] else "") + return CallToolResult(content=parts) + + +async def main() -> None: + owner = "sample-user" # Use the authenticated principal from your application. + model = ScriptedModel( + [ + [ + function_call("inspect_site", {}, call_id="local"), + function_call( + "mcp_Inspection_reports__read_report", {"kind": "structured"}, call_id="remote" + ), + ], + [assistant_message("Reports ready.")], + ] + ) + with closing(Reports(owner)) as reports: + config = RunConfig( + tracing_disabled=True, + tool_execution=ToolExecutionConfig(prepare_tool_output=reports.prepare), + ) + async with ReportServer(reports) as server: + agent = Agent( + name="Inspector", + model=model, + tools=[inspect_site], + mcp_servers=[server], + mcp_config={"include_server_in_tool_names": True}, + ) + result = await Runner.run( + agent, "Inspect both sites.", context=owner, run_config=config + ) + for item in result.new_items: + if item.type == "tool_call_output_item": + summary = item.output if isinstance(item.output, str) else item.output["text"] + print(summary) + reference = summary.split("Reference: ")[1] + page = reports.fetch(owner, reference) + print(f"Retrieved {len(page)} characters privately.") + + +if __name__ == "__main__": + asyncio.run(main()) diff --git a/examples/mcp/bounded_tool_output/server.py b/examples/mcp/bounded_tool_output/server.py new file mode 100644 index 0000000000..2918c4b9c8 --- /dev/null +++ b/examples/mcp/bounded_tool_output/server.py @@ -0,0 +1,66 @@ +"""Synthetic reports for the local stdio example.""" + +from mcp.types import CallToolResult + +try: + from mcp.server.mcpserver import MCPServer +except ImportError: + from mcp.server.fastmcp import FastMCP as MCPServer + +server = MCPServer("Reports") + + +@server.tool(name="read.report") +async def read_report(kind: str) -> CallToolResult: + """Read a sample inspection report.""" + detail = "WARN: synthetic detail " * 4 + if kind == "audio": + return CallToolResult.model_validate( + {"content": [{"type": "audio", "mimeType": "audio/wav", "data": "QUJD"}]} + ) + if kind == "ticket": + return CallToolResult.model_validate( + {"content": [], "structuredContent": {"ticket": "site"}} + ) + if kind in ("text", "brief"): + return CallToolResult.model_validate( + { + "content": [ + {"type": "text", "text": "Sample reading. " * (12 if kind == "text" else 1)} + ] + } + ) + if kind in ("illustrated", "combined"): + return CallToolResult.model_validate( + { + "structuredContent": {"report": detail * 3} if kind == "combined" else None, + "content": [ + {"type": "text", "text": detail}, + { + "type": "image", + "mimeType": "image/gif", + "data": "R0lGODlhAQABAIAAAAAAAP///ywAAAAAAQABAAACAUwAOw==", + }, + {"type": "text", "text": detail}, + ], + } + ) + return CallToolResult.model_validate( + { + "content": [ + { + "type": "text", + "text": "Fallback report" + if kind == "structured" + else "Report unavailable. " * 10, + } + ], + "structuredContent": {"report": detail * 2}, + "_meta": {"private": detail}, + "isError": kind != "structured", + } + ) + + +if __name__ == "__main__": + server.run() diff --git a/tests/mcp/test_bounded_tool_output_example.py b/tests/mcp/test_bounded_tool_output_example.py new file mode 100644 index 0000000000..a9640c61c7 --- /dev/null +++ b/tests/mcp/test_bounded_tool_output_example.py @@ -0,0 +1,217 @@ +import asyncio +import json +from contextlib import closing +from typing import Any + +import pytest + +from agents import Agent, RunConfig, Runner, SQLiteSession, ToolExecutionConfig, UserError +from agents.mcp import MCPToolCustomDataContext +from agents.testing import ScriptedModel, assistant_message, function_call +from agents.tool_context import ToolContext +from examples.mcp.bounded_tool_output import main as recipe +from tests.testing_processor import fetch_ordered_spans + +OWNER = "sample-user" + + +def config(reports: recipe.Reports) -> RunConfig: + return RunConfig( + trace_include_sensitive_data=True, + tool_execution=ToolExecutionConfig(prepare_tool_output=reports.prepare), + ) + + +@pytest.mark.asyncio +async def test_sdk_discovery_and_function_results_before_publication(): + observed = {} + + def observe(result: MCPToolCustomDataContext) -> None: + assert isinstance(result.run_context, ToolContext) + observed[result.run_context.tool_call_id] = ( + result.run_context.context, + result.server_name, + result.tool_name, + result.tool_output, + result.structured_content, + result.result_meta, + result.is_error, + ) + + name = "mcp_Inspection_reports__read_report" + model = ScriptedModel( + [ + [ + function_call("inspect_site", {}, call_id="site"), + function_call(name, {"kind": "structured"}, call_id="json"), + function_call(name, {"kind": "illustrated"}, call_id="mixed"), + function_call(name, {"kind": "combined"}, call_id="combined"), + function_call(name, {"kind": "ticket"}, call_id="ticket"), + function_call(name, {"kind": "missing"}, call_id="error"), + function_call(name, {"kind": "text"}, call_id="text"), + function_call(name, {"kind": "brief"}, call_id="brief"), + function_call("mcp_Other__read_report", {"kind": "text"}, call_id="other"), + ], + [assistant_message("Done")], + ] + ) + with closing(recipe.Reports(OWNER)) as reports, closing(SQLiteSession("reports")) as session: + async with ( + recipe.ReportServer(reports) as selected, + recipe.ReportServer(reports, "Other") as other, + ): + selected.custom_data_extractor = observe + agent = Agent( + name="Inspector", + model=model, + tools=[recipe.inspect_site], + mcp_servers=[selected, other], + mcp_config={"include_server_in_tool_names": True}, + ) + result = Runner.run_streamed( + agent, "Inspect", context=OWNER, run_config=config(reports), session=session + ) + events = [event async for event in result.stream_events()] + + detail = "WARN: synthetic detail " * 4 + structured = json.dumps({"report": detail * 2}) + image = "data:image/gif;base64,R0lGODlhAQABAIAAAAAAAP///ywAAAAAAQABAAACAUwAOw==" + assert observed["json"][:3] == (OWNER, "Inspection reports", "read.report") + assert observed["json"][4:6] == (None, None) + assert observed["error"][-1] is True + assert observed["mixed"][3][1] == {"type": "image", "image_url": image} + spans = [span.export() for span in fetch_ordered_spans()] + assert "Inspection report with 8 warning markers" in repr(spans) + + history = result.to_input_list() + request = model.calls[1].input + for surface in ( + events, + spans, + observed["json"], + result.new_items, + history, + request, + result.context_wrapper, + result.to_state().to_json(), + await session.get_items(), + ): + assert "synthetic detail" not in repr(surface) + assert "synthetic site detail" not in repr(surface) + assert "Fallback report" not in repr(surface) + + outputs = { + i["call_id"]: i["output"] for i in request if i.get("type") == "function_call_output" + } + assert outputs["error"] == [{"type": "input_text", "text": "Report unavailable. " * 10}] + assert outputs["brief"] == [{"type": "input_text", "text": "Sample reading. "}] + assert outputs["other"] == [{"type": "input_text", "text": "Sample reading. " * 12}] + assert ( + outputs["combined"][1:] + == outputs["mixed"][1:] + == [ + {"type": "input_image", "image_url": image}, + {"type": "input_text", "text": ""}, + ] + ) + for summary, count, original in [ + (outputs["site"], 20, ("WARN: synthetic site detail\n" * 20,)), + (outputs["json"][0]["text"], 8, (structured,)), + (outputs["combined"][0]["text"], 12, (json.dumps({"report": detail * 3}),)), + ( + outputs["ticket"][0]["text"], + 20, + (json.dumps({"report": "WARN: synthetic site detail\n" * 20}),), + ), + (outputs["mixed"][0]["text"], 8, (detail, detail)), + (outputs["text"][0]["text"], 0, ("Sample reading. " * 12,)), + ]: + assert len(summary.encode()) <= 128 + label, ref = summary.split(" Reference: ") + assert label == f"Inspection report with {count} warning markers." + assert ref in repr(events) and ref in repr(history) and ref in repr(result.new_items) + for part, expected in enumerate(original): + for offset in range(0, len(expected), 64): + assert ( + reports.fetch(OWNER, ref, part=part, offset=offset) + == expected[offset : offset + 64] + ) + with pytest.raises(PermissionError): + reports.fetch("other-user", ref) + + with closing(recipe.Reports(OWNER)) as other_session, pytest.raises(PermissionError): + other_session.fetch(OWNER, ref) + with pytest.raises(PermissionError): + reports.fetch(OWNER, ref) + + +@pytest.mark.asyncio +@pytest.mark.parametrize( + "invalid", [None, {"text": "private"}, "é" * 64], ids=["missing", "object", "oversized"] +) +async def test_invalid_summary_never_reaches_model_or_events(monkeypatch, invalid): + async def bad_summary(texts: tuple[str, ...]) -> Any: + return invalid + + monkeypatch.setattr(recipe, "summarize", bad_summary) + model = ScriptedModel([[function_call("inspect_site", {}, call_id="site")]]) + agent = Agent(name="Inspector", model=model, tools=[recipe.inspect_site]) + with closing(recipe.Reports(OWNER)) as reports: + result = Runner.run_streamed(agent, "Inspect", context=OWNER, run_config=config(reports)) + with pytest.raises(UserError, match="summary"): + async for event in result.stream_events(): + assert getattr(event, "name", None) != "tool_output" + assert len(model.calls) == 1 + assert all(item.type != "tool_call_output_item" for item in result.new_items) + + +@pytest.mark.asyncio +@pytest.mark.parametrize(("kind", "reason"), [("structured", "summary"), ("audio", "media")]) +async def test_rejected_mcp_output_withholds_raw_report_from_tracing(monkeypatch, kind, reason): + async def invalid(texts: tuple[str, ...]) -> str: + assert texts == (json.dumps({"report": "WARN: synthetic detail " * 8}),) + return "" + + monkeypatch.setattr(recipe, "summarize", invalid) + model = ScriptedModel([[function_call("read.report", {"kind": kind}, call_id="report")]]) + with closing(recipe.Reports(OWNER)) as reports: + async with recipe.ReportServer(reports) as server: + agent = Agent(name="Inspector", model=model, mcp_servers=[server]) + with pytest.raises(UserError, match=reason): + await Runner.run(agent, "Inspect", context=OWNER, run_config=config(reports)) + spans = [span.export() for span in fetch_ordered_spans()] + assert reason in repr(spans) + assert "QUJD" not in repr(spans) + assert "synthetic detail" not in repr(spans) + assert "Fallback report" not in repr(spans) + assert len(model.calls) == 1 + + +@pytest.mark.asyncio +async def test_cancel_during_mcp_ticket_resolution(monkeypatch): + started = asyncio.Event() + stopped = asyncio.Event() + + async def pending_report() -> str: + started.set() + try: + return await asyncio.Future() + finally: + stopped.set() + + monkeypatch.setattr(recipe, "site_report", pending_report) + model = ScriptedModel([[function_call("read.report", {"kind": "ticket"}, call_id="ticket")]]) + with closing(recipe.Reports(OWNER)) as reports: + async with recipe.ReportServer(reports) as server: + agent = Agent(name="Inspector", model=model, mcp_servers=[server]) + task = asyncio.create_task( + Runner.run(agent, "Inspect", context=OWNER, run_config=config(reports)) + ) + try: + await asyncio.wait_for(started.wait(), 5) + finally: + task.cancel() + with pytest.raises(asyncio.CancelledError): + await task + await asyncio.wait_for(stopped.wait(), 5) + assert len(model.calls) == 1 From 334676d22d3af2fd2d7d5033653579892ba5f541 Mon Sep 17 00:00:00 2001 From: Mark Stuart Date: Sat, 21 Nov 2026 07:32:50 -0800 Subject: [PATCH 2/2] Check report access and limit output inside the example tools --- examples/mcp/bounded_tool_output/README.md | 6 +- examples/mcp/bounded_tool_output/main.py | 61 ++++---- tests/mcp/test_bounded_tool_output_example.py | 135 +++++++++++++++--- 3 files changed, 156 insertions(+), 46 deletions(-) diff --git a/examples/mcp/bounded_tool_output/README.md b/examples/mcp/bounded_tool_output/README.md index 7207bd209b..a0c0171981 100644 --- a/examples/mcp/bounded_tool_output/README.md +++ b/examples/mcp/bounded_tool_output/README.md @@ -12,16 +12,16 @@ Both inspection reports exceed the example's 128-byte text budget. The next mode [main.py](main.py) uses two routes. -- For the local `inspect_site` function, the SDK awaits the operation. Then `ToolExecutionConfig.prepare_tool_output` checks that the result is a string and applies the budget. +- `reports.site_tool()` binds `inspect_site` to the private store. The function checks access before reading the report, applies the budget and checks access again before returning. Any output editor receives the result after those checks. - For SDK-discovered MCP tools, `ReportServer.call_tool` awaits the peer and selects successful `read.report` calls on the configured `Inspection reports` server. At this point the wrapper can still check `isError` and see every block. It replaces large reports before SDK conversion, custom data extraction and function span output capture. For a nonempty structured object, the wrapper uses its JSON in place of the fallback text. It resolves the sample `{"ticket": "site"}` by awaiting a local report. The SDK calls `authorize_call` with the run context before sending the request. Never let a server pick another user's record or an arbitrary file or URL. -The budget covers the sum of UTF-8 text bytes per result, including the reference. Smaller reports pass through in full. For large reports, the summary shares only the count of literal `WARN:` markers. Choose facts safe to disclose for your data. The first text slot holds the replacement and the other text slots stay empty. A structured result without a text slot gets one. +At the tool boundary, the budget covers the sum of UTF-8 text bytes per result, including the reference. Smaller reports pass through in full. For large reports, the summary shares only the count of literal `WARN:` markers. Choose facts safe to disclose for your data. The first text slot holds the replacement and the other text slots stay empty. A structured result without a text slot gets one. ## Retrieve privately -Create one `Reports` instance per run. Get the owner and the requester from your application's authentication system. Never accept either identity from tool arguments or a reference. Call `reports.fetch(requester, reference, part=0, offset=0)` in application code. Each page contains up to 64 characters. Advance the offset by the page length, or select another text part. Structured reports have one JSON part. +Create one `Reports` instance per run. Load the owner from a trusted application record. Pass only the authenticated requester as the run context. Never accept either identity from tool arguments or a reference. Call `reports.fetch(requester, reference, part=0, offset=0)` in application code. Each page contains up to 64 characters. Advance the offset by the page length, or select another text part. Structured reports have one JSON part. The originals stay in process memory outside SDK context. Leaving the `closing` block revokes every reference, including on failure or cancellation. Saved conversations cannot restore the originals. This example has no storage quota or durable store. diff --git a/examples/mcp/bounded_tool_output/main.py b/examples/mcp/bounded_tool_output/main.py index f1de2d7e5b..45cb5ac284 100644 --- a/examples/mcp/bounded_tool_output/main.py +++ b/examples/mcp/bounded_tool_output/main.py @@ -13,7 +13,7 @@ from mcp.types import CallToolResult, ImageContent, TextContent -from agents import Agent, RunConfig, Runner, ToolCallHookContext, ToolExecutionConfig, UserError +from agents import Agent, FunctionTool, RunConfig, RunContextWrapper, Runner, UserError from agents.decorators import tool from agents.mcp import MCPServerStdio, MCPToolMetaContext from agents.testing import ScriptedModel, assistant_message, function_call @@ -27,12 +27,6 @@ async def site_report() -> str: return "WARN: synthetic site detail\n" * 20 -@tool(failure_error_function=None) -async def inspect_site() -> str: - """Read the local inspection report.""" - return await site_report() - - async def summarize(texts: tuple[str, ...]) -> str: """Share only the number of warning markers in these synthetic reports.""" count = await asyncio.to_thread(lambda: sum(text.count("WARN:") for text in texts)) @@ -57,17 +51,28 @@ def fetch(self, requester: str, reference: str, *, part: int = 0, offset: int = raise ValueError("Use a nonnegative part and offset") return self._texts[reference][part][offset : offset + 64] + def ensure_open(self) -> None: + if self._texts is None: + raise PermissionError("Report unavailable") + def authorize(self, requester: str) -> None: - if self._texts is None or requester != self._owner: + self.ensure_open() + if requester != self._owner: raise PermissionError("Report unavailable") - async def prepare(self, call: ToolCallHookContext[str], output: Any) -> Any: - if call.tool is not inspect_site: - return output - self.authorize(call.run_context.context) - if not isinstance(output, str): - raise UserError("Expected a report string") - return await self.bound((output,)) or output + def site_tool(self) -> FunctionTool: + @tool(failure_error_function=None) + async def inspect_site(ctx: RunContextWrapper[str]) -> str: + """Read the local inspection report.""" + self.authorize(ctx.context) + text = await site_report() + if not isinstance(text, str): + raise UserError("Expected a report string") + replacement = await self.bound((text,)) + self.authorize(ctx.context) + return replacement or text + + return inspect_site async def bound(self, texts: tuple[str, ...]) -> str | None: if sum(len(text.encode()) for text in texts) <= MAX_TEXT_BYTES: @@ -115,6 +120,7 @@ async def call_tool( fields = result.model_dump(by_alias=True, exclude={"content", "meta"}) if fields.get("isError"): return result + self.reports.ensure_open() if any(not isinstance(block, (TextContent, ImageContent)) for block in result.content): raise UserError("Unsupported report media") @@ -123,12 +129,14 @@ async def call_tool( if structured == {"ticket": "site"}: structured = {"report": await site_report()} text = json.dumps(structured) - replacement = await self.reports.bound((text,)) or text + replacement: str | None = await self.reports.bound((text,)) or text else: texts = tuple(part.text for part in result.content if isinstance(part, TextContent)) replacement = await self.reports.bound(texts) - if replacement is None: - return result + + self.reports.ensure_open() + if replacement is None: + return result # Start a new result so neither structuredContent nor _meta carries the original. parts = list(result.content) @@ -141,7 +149,7 @@ async def call_tool( async def main() -> None: - owner = "sample-user" # Use the authenticated principal from your application. + requester = "sample-user" # Use the authenticated principal from your application. model = ScriptedModel( [ [ @@ -153,28 +161,27 @@ async def main() -> None: [assistant_message("Reports ready.")], ] ) - with closing(Reports(owner)) as reports: - config = RunConfig( - tracing_disabled=True, - tool_execution=ToolExecutionConfig(prepare_tool_output=reports.prepare), - ) + with closing(Reports(owner="sample-user")) as reports: async with ReportServer(reports) as server: agent = Agent( name="Inspector", model=model, - tools=[inspect_site], + tools=[reports.site_tool()], mcp_servers=[server], mcp_config={"include_server_in_tool_names": True}, ) result = await Runner.run( - agent, "Inspect both sites.", context=owner, run_config=config + agent, + "Inspect both sites.", + context=requester, + run_config=RunConfig(tracing_disabled=True), ) for item in result.new_items: if item.type == "tool_call_output_item": summary = item.output if isinstance(item.output, str) else item.output["text"] print(summary) reference = summary.split("Reference: ")[1] - page = reports.fetch(owner, reference) + page = reports.fetch(requester, reference) print(f"Retrieved {len(page)} characters privately.") diff --git a/tests/mcp/test_bounded_tool_output_example.py b/tests/mcp/test_bounded_tool_output_example.py index a9640c61c7..56967f0777 100644 --- a/tests/mcp/test_bounded_tool_output_example.py +++ b/tests/mcp/test_bounded_tool_output_example.py @@ -5,7 +5,15 @@ import pytest -from agents import Agent, RunConfig, Runner, SQLiteSession, ToolExecutionConfig, UserError +from agents import ( + Agent, + AgentsException, + RunConfig, + Runner, + SQLiteSession, + ToolExecutionConfig, + UserError, +) from agents.mcp import MCPToolCustomDataContext from agents.testing import ScriptedModel, assistant_message, function_call from agents.tool_context import ToolContext @@ -15,13 +23,6 @@ OWNER = "sample-user" -def config(reports: recipe.Reports) -> RunConfig: - return RunConfig( - trace_include_sensitive_data=True, - tool_execution=ToolExecutionConfig(prepare_tool_output=reports.prepare), - ) - - @pytest.mark.asyncio async def test_sdk_discovery_and_function_results_before_publication(): observed = {} @@ -64,12 +65,16 @@ def observe(result: MCPToolCustomDataContext) -> None: agent = Agent( name="Inspector", model=model, - tools=[recipe.inspect_site], + tools=[reports.site_tool()], mcp_servers=[selected, other], mcp_config={"include_server_in_tool_names": True}, ) result = Runner.run_streamed( - agent, "Inspect", context=OWNER, run_config=config(reports), session=session + agent, + "Inspect", + context=OWNER, + run_config=RunConfig(trace_include_sensitive_data=True), + session=session, ) events = [event async for event in result.stream_events()] @@ -145,6 +150,59 @@ def observe(result: MCPToolCustomDataContext) -> None: reports.fetch(OWNER, ref) +@pytest.mark.asyncio +async def test_local_tool_denies_access_before_reading(monkeypatch): + async def forbidden(): + pytest.fail("Unauthorized caller reached the report reader") + + monkeypatch.setattr(recipe, "site_report", forbidden) + model = ScriptedModel([[function_call("inspect_site", {}, call_id="site")]]) + with closing(recipe.Reports(OWNER)) as reports: + agent = Agent(name="Inspector", model=model, tools=[reports.site_tool()]) + with pytest.raises(UserError, match="Report unavailable"): + await Runner.run(agent, "Inspect", context="other-user") + assert len(model.calls) == 1 + + +@pytest.mark.asyncio +async def test_local_tool_rechecks_access_before_returning_a_small_report(monkeypatch): + model = ScriptedModel([[function_call("inspect_site", {}, call_id="site")]]) + with closing(recipe.Reports(OWNER)) as reports: + + async def revoke(): + reports.close() + return "Private reading" + + monkeypatch.setattr(recipe, "site_report", revoke) + agent = Agent(name="Inspector", model=model, tools=[reports.site_tool()]) + with pytest.raises(UserError, match="Report unavailable"): + await Runner.run(agent, "Inspect", context=OWNER) + assert len(model.calls) == 1 + + +@pytest.mark.asyncio +async def test_local_output_is_bounded_before_an_independent_editor(): + seen = [] + + async def replace(call, output): + seen.append(output) + return "Reviewed" + + model = ScriptedModel( + [[function_call("inspect_site", {}, call_id="site")], [assistant_message("Done")]] + ) + with closing(recipe.Reports(OWNER)) as reports: + agent = Agent(name="Inspector", model=model, tools=[reports.site_tool()]) + config = RunConfig(tool_execution=ToolExecutionConfig(prepare_tool_output=replace)) + await Runner.run(agent, "Inspect", context=OWNER, run_config=config) + (summary,) = seen + assert len(summary.encode()) <= 128 + label, ref = summary.split(" Reference: ") + assert label == "Inspection report with 20 warning markers." + assert reports.fetch(OWNER, ref) == (await recipe.site_report())[:64] + assert "Reviewed" in repr(model.calls[1].input) + + @pytest.mark.asyncio @pytest.mark.parametrize( "invalid", [None, {"text": "private"}, "é" * 64], ids=["missing", "object", "oversized"] @@ -155,9 +213,9 @@ async def bad_summary(texts: tuple[str, ...]) -> Any: monkeypatch.setattr(recipe, "summarize", bad_summary) model = ScriptedModel([[function_call("inspect_site", {}, call_id="site")]]) - agent = Agent(name="Inspector", model=model, tools=[recipe.inspect_site]) with closing(recipe.Reports(OWNER)) as reports: - result = Runner.run_streamed(agent, "Inspect", context=OWNER, run_config=config(reports)) + agent = Agent(name="Inspector", model=model, tools=[reports.site_tool()]) + result = Runner.run_streamed(agent, "Inspect", context=OWNER) with pytest.raises(UserError, match="summary"): async for event in result.stream_events(): assert getattr(event, "name", None) != "tool_output" @@ -178,7 +236,12 @@ async def invalid(texts: tuple[str, ...]) -> str: async with recipe.ReportServer(reports) as server: agent = Agent(name="Inspector", model=model, mcp_servers=[server]) with pytest.raises(UserError, match=reason): - await Runner.run(agent, "Inspect", context=OWNER, run_config=config(reports)) + await Runner.run( + agent, + "Inspect", + context=OWNER, + run_config=RunConfig(trace_include_sensitive_data=True), + ) spans = [span.export() for span in fetch_ordered_spans()] assert reason in repr(spans) assert "QUJD" not in repr(spans) @@ -204,9 +267,7 @@ async def pending_report() -> str: with closing(recipe.Reports(OWNER)) as reports: async with recipe.ReportServer(reports) as server: agent = Agent(name="Inspector", model=model, mcp_servers=[server]) - task = asyncio.create_task( - Runner.run(agent, "Inspect", context=OWNER, run_config=config(reports)) - ) + task = asyncio.create_task(Runner.run(agent, "Inspect", context=OWNER)) try: await asyncio.wait_for(started.wait(), 5) finally: @@ -215,3 +276,45 @@ async def pending_report() -> str: await task await asyncio.wait_for(stopped.wait(), 5) assert len(model.calls) == 1 + + +@pytest.mark.asyncio +@pytest.mark.parametrize( + ("kind", "close_at"), [("brief", "peer"), ("ticket", "peer"), ("ticket", "read")] +) +async def test_closed_store_withholds_short_mcp_reports(monkeypatch, kind, close_at): + model = ScriptedModel( + [ + [function_call("read.report", {"kind": kind}, call_id="report")], + [assistant_message("Done")], + ] + ) + with closing(recipe.Reports(OWNER)) as reports: + peer = recipe.MCPServerStdio.call_tool + + async def receive(*args, **kwargs): + result = await peer(*args, **kwargs) + if close_at == "peer": + reports.close() + return result + + async def read(): + if close_at != "read": + pytest.fail("Closed store reached the ticket reader") + reports.close() + return "Private reading" + + monkeypatch.setattr(recipe.MCPServerStdio, "call_tool", receive) + monkeypatch.setattr(recipe, "site_report", read) + async with recipe.ReportServer(reports) as server: + agent = Agent(name="Inspector", model=model, mcp_servers=[server]) + with pytest.raises(AgentsException, match="Report unavailable"): + await Runner.run( + agent, + "Inspect", + context=OWNER, + run_config=RunConfig(trace_include_sensitive_data=True), + ) + assert len(model.calls) == 1 + spans = repr([span.export() for span in fetch_ordered_spans()]) + assert "Private reading" not in spans and "Sample reading" not in spans