Skip to content

Python: preserve sources for toolbox citations - #10392

Open
sophia-ramsey wants to merge 6 commits into
python-foundry-hosting-rcfrom
sramsey/python-hosting-toolbox-citations
Open

sophia-ramsey wants to merge 6 commits into
python-foundry-hosting-rcfrom
sramsey/python-hosting-toolbox-citations

Conversation

@sophia-ramsey

Copy link
Copy Markdown
Member

Motivation & Context

Python hosted agents using Foundry Toolbox can complete web searches but return final answers without citations, even when the Toolbox returns citation metadata. The default MCP result handling also drops the search text, leaving the model with citation JSON instead.

Description & Review Guide

  • What are the major changes?
    Core MCP parsing now recognizes URL citations and, for cited results using the default structured_first mode, preserves the search text alongside the structured result. Foundry hosting collects those sources and attaches them to the final answer at its end, without claiming they support a specific passage.
  • What is the impact of these changes?
    Foundry Toolbox agents and generic MCP tools connected to Toolbox can return clickable sources in hosted responses, while native web search behavior remains unchanged. This applies to the default result mode; custom parsing or another result mode can opt out of the core handling.
  • What do you want reviewers to focus on?
    The solution approach to include cited sources grouped at the end of the text due to lack of start/end information for sources, compared to native web search which has access to that information
# Toolbox web search with this fix
Mars is red because of iron oxide dust. Its thin atmosphere
scatters red light, giving the sky a butterscotch tint.[1][2]

Sources
[1] Mars Facts – nasa.gov
[2] ESA Mars – esa.int

# Native web search
Mars is red because of iron oxide dust.[1] Its thin atmosphere
scatters red light, giving the sky a butterscotch tint.[2]

Sources
[1] Mars Facts – nasa.gov
[2] ESA Mars – esa.gov

Related Issue

Fixes #10325

Related: takes the changes from #10327 and applies to python-foundry-hosting-rc instead of main

AI Assistance

  • No material AI assistance was used.
  • This is an AI-assisted contribution. I reviewed, understood, and verified all submitted content and accept responsibility for it.

AI assistance details: planning, implementation, testing

Contribution Checklist

  • The code builds clean without any errors or warnings
  • All unit tests pass, and I have added new tests where possible
  • The PR follows the Contribution Guidelines
  • This PR links to an agreed issue with no competing open PR, or the Related Issue section documents a trivial-change or repository-automation exception.
  • This is not a breaking change. If it is a breaking change, add the breaking change label (or add "[BREAKING]" to the title prefix, before or after any language prefix) — a workflow keeps the label and title prefix in sync automatically.

@sophia-ramsey
sophia-ramsey deployed to github-app-auth November 16, 2026 20:42 — with GitHub Actions Active
@sophia-ramsey sophia-ramsey changed the title Sramsey/python hosting toolbox citations Python: preserve sources for toolbox citations Nov 16, 2026
@sophia-ramsey
sophia-ramsey deployed to github-app-auth November 16, 2026 20:42 — with GitHub Actions Active
@sophia-ramsey
sophia-ramsey deployed to github-app-auth November 16, 2026 20:42 — with GitHub Actions Active
@agent-framework-automation agent-framework-automation Bot added documentation Usage: [Issues, PRs], Target: documentation in the code base and learn docs python Usage: [Issues, PRs], Target: Python labels Nov 16, 2026

@github-actions github-actions Bot left a comment

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

MAF Automated Review — Iteration 1

Result: Findings reported
Scope: full PR (6 commit(s)): d3a9dfe64a4c, 456448e74b8e, 0fa38125aa6c, 0a2f4760e77d, c6df8f69e465, be0f10ff6824
Model: gpt-5.6-sol

Overview

The PR validates and projects MCP URL citations, bounds response-local hosted source state, and preserves citations across persisted responses with broad targeted coverage. Its MCP parsing guards and hosted URL/count/byte limits constrain malformed metadata and unsafe source schemes. Two workflow lifecycle gaps remain: deferred superstep persistence can lose a completed checkpoint during resilient shutdown, and final sources can be discarded when a designated output is followed by a trailing intermediate event.

Reviewed the supplied pull-request change set across correctness, security/reliability, architecture, and failure behavior.
2 verified findings remained after source verification (1 high, 1 medium) across 1 file. Details are attached to the affected lines below.

Affected areas: python/packages/foundry_hosting/agent_framework_foundry_hosting/_responses_workflow.py

if resilient:
yield stream.checkpoint()
pending_checkpoint = iterator.stamp
pending_flush = True

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Deferring the stage here leaves a recovery gap: if context.shutdown wins the next _SignalledIterator.__anext__, control exits through iterator.signalled before the pending_flush block runs. The completed superstep's checkpoint and output are never paired via run.stage(), so recovery resumes from the prior snapshot and can rerun already-completed side effects. Please flush/stage any pending completed superstep before exit_for_recovery(), or keep checkpoint staging immediate and defer only final-answer citation attachment.

for event in buffered:
events.extend(await _project(event, draft, next_tracker, checkpoint, next_aliases))
events.extend(next_tracker.close())
is_final_output = final_answer and bool(buffered) and buffered[-1].type == "output"

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

This makes final-answer selection depend on event arrival order. A valid terminal superstep can contain both designated output and intermediate/data events, and if an intermediate arrives last, the sources remain unattached and are immediately discarded. Please identify and finalize the designated output independently of trailing interim events, while preserving the current behavior for intermediate-only workflows.

This branch was successfully deployed

1 active deployment
github-app-auth — be0f10ff Deployed Nov 16, 2026 by sophia-ramsey via add_label #27924
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

documentation Usage: [Issues, PRs], Target: documentation in the code base and learn docs python Usage: [Issues, PRs], Target: Python

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant