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
169 changes: 167 additions & 2 deletions python/packages/core/agent_framework/_mcp.py
Original file line number Diff line number Diff line change
Expand Up @@ -10,6 +10,8 @@
import sys
import warnings
from abc import abstractmethod
from array import array
from bisect import bisect_left
from collections.abc import AsyncGenerator, Awaitable, Callable, Collection, Coroutine, Generator, Mapping, Sequence
from contextlib import AsyncExitStack, _AsyncGeneratorContextManager, asynccontextmanager, contextmanager # type: ignore
from contextvars import ContextVar
Expand Down Expand Up @@ -46,6 +48,7 @@
_FunctionResultPayloadBudget, # pyright: ignore[reportPrivateUsage]
)
from ._types import (
Annotation,
ChatOptions,
Content,
Message,
Expand Down Expand Up @@ -194,7 +197,11 @@ class MCPSpecificApproval(TypedDict, total=False):
MCP servers disagree on whether the two fields are duplicates or complementary (#7866).
Callers pick an explicit policy:

- ``structured_first`` (default): use ``structuredContent`` when present, else ``content``
- ``structured_first`` (default): use ``structuredContent`` when present, else ``content``. When the result
has text content and ``url_citation`` entries in ``structuredContent.annotations`` or a content block's
``_meta.annotations`` (for example, Foundry Toolbox web search), the text content is kept before
``structuredContent`` and the citations are attached as framework annotations. Without text content, citations
are attached without spans to the selected structured result, when present.
- ``content_first``: use ``content`` when non-empty, else ``structuredContent``
- ``content_only``: ignore ``structuredContent`` for the model-visible result
- ``structured_only``: ignore ``content`` for the model-visible result
Expand All @@ -204,6 +211,161 @@ class MCPSpecificApproval(TypedDict, total=False):
Custom ``parse_tool_results`` overrides this policy entirely.
"""

_MCPCitationKey: TypeAlias = tuple[str, str | None, int | None, int | None]


def _utf16_surrogate_offsets(text: str) -> tuple[int, array[int]]:
"""Return UTF-16 length and low-surrogate offsets belonging to pairs."""
offset = 0
previous_high = False
low_offsets = array("Q")
for character in text:
code = ord(character)
if code > 0xFFFF:
low_offsets.append(offset + 1)
offset += 2
previous_high = False
else:
if previous_high and 0xDC00 <= code <= 0xDFFF:
low_offsets.append(offset)
previous_high = 0xD800 <= code <= 0xDBFF
offset += 1
return offset, low_offsets


def _parse_mcp_url_citation(value: Any) -> tuple[Annotation, _MCPCitationKey] | None:
"""Validate an MCP ``url_citation`` entry."""
if not isinstance(value, Mapping):
return None
raw = cast(Mapping[str, Any], value)
url = raw.get("url")
if raw.get("type") != "url_citation" or not isinstance(url, str) or not url.strip():
return None

raw_title = raw.get("title")
title = raw_title if isinstance(raw_title, str) else None
raw_start, raw_end = raw.get("start_index"), raw.get("end_index")
start = raw_start if type(raw_start) is int else None
end = raw_end if type(raw_end) is int else None
citation = Annotation(type="citation", url=url)
if title is not None:
citation["title"] = title
return citation, (url, title, start, end)


def _attach_mcp_citation_span(
citation: Annotation, key: _MCPCitationKey, text_utf16_length: int, low_offsets: Sequence[int]
) -> None:
_, _, start, end = key
if start is not None and end is not None and 0 <= start <= end <= text_utf16_length:
# Citation offsets use UTF-16 code units; framework spans use Python text offsets.
start_pairs = bisect_left(low_offsets, start)
end_pairs = bisect_left(low_offsets, end)
if (start_pairs == len(low_offsets) or low_offsets[start_pairs] != start) and (
end_pairs == len(low_offsets) or low_offsets[end_pairs] != end
):
citation["annotated_regions"] = [
{
"type": "text_span",
"start_index": start - start_pairs,
"end_index": end - end_pairs,
}
]


def _mcp_block_annotations(item: Any) -> list[Any]:
"""Collect annotation metadata from an MCP content block and its embedded resource."""
metadata: list[Any] = [getattr(item, "meta", None)]
resource = getattr(item, "resource", None)
if resource is not None:
metadata.append(getattr(resource, "meta", None))
annotations: list[Any] = []
for entry in metadata:
if isinstance(entry, Mapping):
values = cast(Mapping[str, Any], entry).get("annotations")
if isinstance(values, list):
annotations.extend(cast(list[Any], values))
return annotations


def _project_mcp_url_citations(
mcp_type: types.CallToolResult,
content_items: list[Content],
structured_block: Content | None,
) -> list[Content] | None:
"""Keep cited text content before structured content and attach its URL citations as annotations.

When there is no text content, attach recognized citations without spans to the structured block, if present.
Returns ``None`` when the result is an error or has no recognized ``url_citation`` entries. ``content_items``
must hold exactly one parsed item per MCP content block.
"""
if mcp_type.is_error:
return None
structured: Any = mcp_type.structured_content
structured_values = (
cast(Mapping[str, Any], structured).get("annotations") if isinstance(structured, Mapping) else None
)
structured_annotations = cast(list[Any], structured_values) if isinstance(structured_values, list) else []
block_annotations = [_mcp_block_annotations(item) for item in mcp_type.content]
if not any(
_parse_mcp_url_citation(value) is not None
for value in [*structured_annotations, *(value for values in block_annotations for value in values)]
):
return None
has_text_content = any(item.type == "text" and item.text for item in content_items)
if not has_text_content and structured_block is not None:
citations: list[Annotation] = []
seen: set[_MCPCitationKey] = set()
all_annotations = [
*structured_annotations,
*(value for values in block_annotations for value in values),
]
for value in all_annotations:
parsed = _parse_mcp_url_citation(value)
if parsed is not None and parsed[1] not in seen:
citations.append(parsed[0])
seen.add(parsed[1])
if citations:
structured_block.annotations = [*(structured_block.annotations or []), *citations]
return [structured_block]

# Match aggregate and block-owned occurrences without collapsing repeated citations.
block_citations: dict[_MCPCitationKey, int] = {}
for item, values in zip(content_items, block_annotations, strict=True):
text_utf16_length, low_offsets = (
_utf16_surrogate_offsets(item.text)
if values and item.type == "text" and item.text is not None
else (None, array("Q"))
)
item_citations = list(item.annotations or [])
item_seen: set[_MCPCitationKey] = set()
for value in values:
parsed = _parse_mcp_url_citation(value)
if parsed is not None and parsed[1] not in item_seen:
if text_utf16_length is not None:
_attach_mcp_citation_span(parsed[0], parsed[1], text_utf16_length, low_offsets)
item_citations.append(parsed[0])
item_seen.add(parsed[1])
block_citations[parsed[1]] = block_citations.get(parsed[1], 0) + 1
if item_citations:
item.annotations = item_citations

unbound: list[Annotation] = []
for value in structured_annotations:
parsed = _parse_mcp_url_citation(value)
if parsed is None:
continue
if block_citations.get(parsed[1]):
block_citations[parsed[1]] -= 1
else:
unbound.append(parsed[0])
if structured_block is None:
return content_items
if unbound:
structured_block.annotations = [*(structured_block.annotations or []), *unbound]
return [*content_items, structured_block]


_MCP_REMOTE_NAME_KEY = "_mcp_remote_name"
_MCP_IS_TOOL_KEY = "_mcp_is_tool"
_MCP_NORMALIZED_NAME_KEY = "_mcp_normalized_name"
Expand Down Expand Up @@ -1521,7 +1683,10 @@ def _parse_tool_result_from_mcp(
if not result and structured_block is not None:
result.append(structured_block)
elif mode == "structured_first":
if structured_block is not None:
cited = _project_mcp_url_citations(mcp_type, result, structured_block)
if cited is not None:
result = cited
elif structured_block is not None:
result = [structured_block]
else: # pragma: no cover - validated in __init__
raise ValueError(f"Unknown tool_result_content mode: {mode!r}")
Expand Down
92 changes: 92 additions & 0 deletions python/packages/core/tests/core/test_mcp.py
Original file line number Diff line number Diff line change
Expand Up @@ -1412,6 +1412,98 @@ def test_parse_tool_result_content_modes_for_complementary_and_duplicate_payload
assert content_only._parse_tool_result_from_mcp(empty)[0].text == "null"


def test_structured_first_keeps_cited_content_and_attaches_url_citations():
"""Default MCP parsing keeps search text when url_citation metadata is present (for example, Foundry Toolbox)."""
block_citation = {
"type": "url_citation",
"url": "https://example.test/block",
"title": "Block",
"start_index": 0,
"end_index": 4,
}
aggregate_citation = {"type": "url_citation", "url": "https://example.test/aggregate"}
structured = {"annotations": [block_citation, aggregate_citation, {"type": "other"}]}
mcp_result = types.CallToolResult(
content=[types.TextContent(type="text", text="Mars is red.", _meta={"annotations": [block_citation]})],
structured_content=structured,
_meta={"source": "server"},
)

result = _HELPER_MCP_TOOL._parse_tool_result_from_mcp(mcp_result)

assert [item.text for item in result] == ["Mars is red.", json.dumps(structured)]
assert result[0].annotations == [
{
"type": "citation",
"url": "https://example.test/block",
"title": "Block",
"annotated_regions": [{"type": "text_span", "start_index": 0, "end_index": 4}],
}
]
assert result[1].annotations == [{"type": "citation", "url": "https://example.test/aggregate"}]
assert all(item.additional_properties["_meta"] == {"source": "server"} for item in result)


def test_cited_text_converts_multiple_utf16_spans_and_deduplicates():
text = "A\U0001f30eB\U0001f680C"
citations = [
{"type": "url_citation", "url": "https://example.test/earth", "start_index": 1, "end_index": 3},
{"type": "url_citation", "url": "https://example.test/rocket", "start_index": 4, "end_index": 6},
{"type": "url_citation", "url": "https://example.test/invalid", "start_index": 2, "end_index": 6},
]
mcp_result = types.CallToolResult(
content=[types.TextContent(type="text", text=text, _meta={"annotations": [*citations, *citations]})]
)

result = _HELPER_MCP_TOOL._parse_tool_result_from_mcp(mcp_result)

assert result[0].annotations == [
{
"type": "citation",
"url": "https://example.test/earth",
"annotated_regions": [{"type": "text_span", "start_index": 1, "end_index": 2}],
},
{
"type": "citation",
"url": "https://example.test/rocket",
"annotated_regions": [{"type": "text_span", "start_index": 3, "end_index": 4}],
},
{"type": "citation", "url": "https://example.test/invalid"},
]


def test_structured_first_does_not_attach_url_citations_to_error_results():
mcp_result = types.CallToolResult(
content=[types.TextContent(type="text", text="Search failed")],
structured_content={"annotations": [{"type": "url_citation", "url": "https://example.test"}]},
is_error=True,
)

result = _HELPER_MCP_TOOL._parse_tool_result_from_mcp(mcp_result)

assert len(result) == 1
assert result[0].annotations is None


@pytest.mark.parametrize(
"content",
[
[],
[types.TextContent(type="text", text="")],
],
)
def test_structured_first_attaches_unspanned_citations_without_search_text(content):
citation = {"type": "url_citation", "url": "https://example.test/source", "title": "Source"}
structured = {"annotations": [citation]}
mcp_result = types.CallToolResult(content=content, structured_content=structured)

result = _HELPER_MCP_TOOL._parse_tool_result_from_mcp(mcp_result)

assert len(result) == 1
assert result[0].text == json.dumps(structured)
assert result[0].annotations == [{"type": "citation", "url": "https://example.test/source", "title": "Source"}]


async def test_generated_mcp_tool_preserves_complete_host_payload_once() -> None:
"""The generated FunctionTool path retains one complete, persistent Host payload."""
file_meta = {
Expand Down
15 changes: 15 additions & 0 deletions python/packages/foundry_hosting/README.md
Original file line number Diff line number Diff line change
Expand Up @@ -142,6 +142,14 @@ supplied through their configured Toolbox. The private metadata parser is intend
Toolbox; reusing it elsewhere provides no security or compatibility guarantees. It is not a
general-purpose MCP approval policy.

## Toolbox search citations

`FoundryToolbox` and generic MCP tools use the default `structured_first` result handling for Toolbox search results.
When a result contains text content and `url_citation` annotations, the text stays visible to the model before the
structured JSON, and the citations are attached to the tool result. If the result has citations but no text content,
they are attached without spans to the selected structured result. Another `tool_result_content` mode or a custom
`parse_tool_results` replaces this handling, and hosted answers then receive no Toolbox citations.

## Agent instances and factories

`ResponsesHostServer` and `InvocationsHostServer` accept an agent instance or a callable through the
Expand Down Expand Up @@ -446,6 +454,13 @@ Completed provider responses retain separate text content parts, keeping citatio
their original part. Ordinary streaming deltas still merge within their existing text occurrence,
without shifting citation offsets.

Web URL citations on function results, such as `FoundryToolbox` search results, are listed as sources on the
final answer text when the response completes. These citations do not identify which part of the answer each
source supports, so the host emits each one as a zero-length `url_citation` at the end of that text. Sources are
deduplicated by URL, limited to `http` and `https`, skipped when the answer already cites the same URL, and not
attached to interim text. A response retains at most 100 sources and 64 KiB of UTF-8 URL and title data;
additional or oversized sources are skipped with a warning. Plain `agent.run()` responses do not include these sources.

## State store

### Local persistence
Expand Down
Original file line number Diff line number Diff line change
Expand Up @@ -688,7 +688,7 @@ async def _handle_prepared_response(
# below so its partial output is not misreported as a failure.
return

for event in tracker.close():
for event in tracker.close(final_answer=True):
yield event

if cancellation_signal.is_set() and context.client_cancelled:
Expand All @@ -699,7 +699,7 @@ async def _handle_prepared_response(
# selecting the terminal event. Same ``client_cancelled`` gate as above.
return

tracker.discard_pending_container_file_citations()
tracker.discard_pending_citations()
incomplete_reason = tracker.incomplete_reason
if tracker.oauth_consent_requested or incomplete_reason is not None:
yield response_event_stream.emit_incomplete(reason=incomplete_reason, usage=tracker.usage)
Expand Down Expand Up @@ -1124,7 +1124,9 @@ async def publish_update(
yield event
if context.shutdown.is_set() or cancellation_signal.is_set():
continue
for event in tracker.close():
# Unfinished provider outputs end at a function result, so text is still
# active here only when it ends the finished answer.
for event in tracker.close(final_answer=True):
yield event
private_metadata = _hosted_internal_metadata(response_event_stream)
private_metadata[_HOSTED_PROVIDER_OUTPUT_COUNT_KEY] = output_count
Expand Down Expand Up @@ -1517,7 +1519,7 @@ def _emit_failure(
yield from tracker.close()
except Exception as close_error:
_log_response_failure("failed tracker cleanup", response_id, close_error)
tracker.discard_pending_container_file_citations()
tracker.discard_pending_citations()
if public_message is not None:
message = public_message
elif isinstance(ex, _PublicResponseFailure):
Expand Down
Loading
Loading