[Eduard van Valkenburg (eavanvalkenburg)]

Motivation & Context

Python providers, protocol adapters, and hosts independently decided where content identity, replay data, hosted execution ownership, and streaming instructions lived. This produced more than 25 ad hoc additional_properties keys, cross-package dependencies on provider-specific metadata, replay paths that depended on non-persisted SDK objects, and stream aggregation that guessed whether payloads were deltas or snapshots.

The implicit stream heuristic corrupts repetitive code-interpreter output, while the lack of an explicit local-versus-hosted approval boundary can serialize resolved local approvals as provider-hosted MCP approvals. A shared contract is needed across core and every official provider rather than another provider-specific workaround.

Description & Review Guide

• What are the major changes?

  • Approves ADR 0044 and adds normative Spec 005 for Python content identity, hosted routing, protocol metadata, replay, compatibility, and stream aggregation.
  • Adds first-class Content.hosted, server_name, occurrence-aware function-result identity, and explicit merge_mode="append" | "replace" semantics. Final response aggregation consumes the update-only merge mode.
  • Adds one-level additional_properties namespaces and shared read, copy-on-write, and merge helpers. Agent Framework-owned provider-neutral metadata uses core; provider data uses namespaces such as openai, foundry, bedrock, mistral, and a2a.
  • Applies the contract across OpenAI Responses and Chat Completions, Foundry, Foundry hosting, Hosting Responses, DevUI, AG-UI, A2A and Hosting A2A, Anthropic, Bedrock, Gemini, Mistral, Ollama, Claude, GitHub Copilot, and Copilot Studio.
  • Removes AG-UI's synthetic server-call wrapper and declaration-only placeholder tools; provider-owned calls remain ordinary function calls marked hosted=True.
  • Makes replay-critical conversions independent of raw_representation, preserves legacy reads, and dual-writes independently consumed replay metadata where required.
  • Adds cross-package regression coverage for repetitive stream fragments, authoritative snapshots, persisted replay, hosted execution, approval correlation, canonical-only metadata, and legacy compatibility.

• What is the impact of these changes? Provider stream conversion and aggregation now preserve the provider's actual append-versus-replace intent, hosted calls cannot execute locally, local approvals are not projected as MCP approvals, and persisted histories can replay without live SDK objects.

  Breaking-change boundary: upgrading is compatible with histories written by existing releases. However, the new runtime serializes hosted on function-call content and may serialize merge_mode on individual streamed updates. Older Agent Framework runtimes do not recognize these fields and reject those records during Content deserialization. Rolling back after new records have been persisted, or running old and new workers against the same session/history store, is therefore unsupported. Final aggregated responses clear merge_mode, and the new runtime continues to read legacy server_label and metadata locations, so this is specifically a backward-reader and mixed-version persistence break rather than a source-level removal of the existing APIs.

  Release coordination: every Python package changed by this PR must receive a coordinated version bump in the same release, and all inter-package dependency floors must be updated to the corresponding co-released versions. Core, providers, protocol adapters, UI packages, and hosting packages must not be released as a partial subset: newer adapters emit or depend on fields, namespace merging, and replay behavior that older core or sibling packages do not understand.

• What do you want reviewers to focus on? The first-class identity and hosted-execution boundary, whether each provider event is correctly classified as incremental or authoritative, the one-level namespace merge/copy rules, and the compatibility scope for replay-critical metadata.

Related Issue

Fixes #8910

Fixes #8903

Fixes #7452

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: Repository inventory, design and specification drafting, implementation across provider adapters, regression tests, documentation editing, and this PR description.

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.

[Copilot]

Copilot review overview

🟡 Changes recommended

The ADR omits hosted approval-response identity and a security-relevant legacy server-name fallback.

Review effort: Balanced
Findings: 1 · 1

Open (2)

• Fallback to legacy server_label when server_name is absent · New
• Exclude hosted approval responses from ID rewriting · New

What changed in this PR

Adds ADR 0044 defining Python content identity, hosted-call metadata, namespaced protocol metadata, and compatibility rules.

Changes:

• Defines Content.id, call_id, and provider identifier semantics.
• Introduces the proposed hosted field and metadata migration strategy.
• Documents replay and legacy compatibility requirements.

File	Description
docs/​decisions/​0044-python-content-identity-and-protocol-metadata.md	Adds ADR 0044 and implementation guidance.

---

💡 Add a code-review agent skill for context-aware, tailored reviews. Learn more in the docs.

[github-actions]

MAF Automated Review — Iteration 1

Result: Findings reported
Scope: full PR (1 commit(s)): 3860235dd295
Model: gpt-5.6-sol

Overview

The ADR establishes a coherent separation between framework occurrence identity, provider identifiers, hosted execution, and replay metadata, with useful compatibility guardrails through legacy reads, dual-writing, and persisted-history tests. The current source confirms the motivating server_label, fc_id, and raw-representation coupling. Two contract gaps remain: streamed function-call merging is not required to preserve the new hosted marker, and the closed provider-ID exception list omits hosted approval responses that must retain the provider approval ID.

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

Affected areas: docs/decisions/0044-python-content-identity-and-protocol-metadata.md

[Eduard van Valkenburg (eavanvalkenburg)]

/review

[github-actions]

MAF Automated Review — Iteration 3

Result: Findings reported
Scope: full PR (12 commit(s)): 813905710679, 11034587a49f, 0cb8039fb4ba, c265d6091d9e, cfef864eded4, a36eab8ec291, a43d2b5b4cb9, f721cea2de7e, dd83ee663527, 639154615d69, 22dc69aa05f3, 631a6a51fd7b
Model: gpt-5.6-sol

Overview

The PR establishes explicit identity, hosted-routing, metadata, and stream-merge contracts, with strong fail-closed approval handling and focused compatibility tests. Hosted ownership remains fail-safe, finalization clears update-only state, and prior text-snapshot and usage regressions are covered. Residual risk remains in heterogeneous A2A snapshots, authoritative function-call names, and hosted projections that cannot faithfully emit divergent replacement text.

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

Affected areas: python/packages/a2a/agent_framework_a2a/_agent.py, python/packages/core/agent_framework/_types.py, python/packages/foundry_hosting/agent_framework_foundry_hosting/_responses.py

[Jose Alvarez (jpalvarezl)]

Two remaining identity/ownership edge cases to address before merge.

[Eduard van Valkenburg (eavanvalkenburg)]

/review