Skip to content
Open
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
33 changes: 33 additions & 0 deletions examples/mcp/bounded_tool_output/README.md
Original file line number Diff line number Diff line change
@@ -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.

- `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.

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. 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.

## 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.
189 changes: 189 additions & 0 deletions examples/mcp/bounded_tool_output/main.py
Original file line number Diff line number Diff line change
@@ -0,0 +1,189 @@
"""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, 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

MAX_TEXT_BYTES = 128
SERVER = "Inspection reports"


async def site_report() -> str:
"""Read the local inspection report."""
return "WARN: synthetic site detail\n" * 20


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 ensure_open(self) -> None:
if self._texts is None:
raise PermissionError("Report unavailable")

def authorize(self, requester: str) -> None:
self.ensure_open()
if requester != self._owner:
raise PermissionError("Report unavailable")

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:
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
self.reports.ensure_open()
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: 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)

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)
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:
requester = "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="sample-user")) as reports:
async with ReportServer(reports) as server:
agent = Agent(
name="Inspector",
model=model,
tools=[reports.site_tool()],
mcp_servers=[server],
mcp_config={"include_server_in_tool_names": True},
)
result = await Runner.run(
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(requester, reference)
print(f"Retrieved {len(page)} characters privately.")


if __name__ == "__main__":
asyncio.run(main())
66 changes: 66 additions & 0 deletions examples/mcp/bounded_tool_output/server.py
Original file line number Diff line number Diff line change
@@ -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()
Loading