Python: [BREAKING] restore agent middleware API contract

[Eduard van Valkenburg (eavanvalkenburg)]

Motivation & Context

The agent-hooks integration introduced two unrelated changes to the core package surface: an agent-framework-core[agent-hooks] extra and support for singular middleware values on agents and create_harness_agent. The singular form conflicts with the sequence-only API decision recorded in #2902, and the experimental integration should not add a core package extra.

Description & Review Guide

• What are the major changes? Removes the agent-hooks extra from core package metadata and directs users to install agent-hooks-sdk separately. Restores sequence-only middleware inputs across BaseAgent, RawAgent, Agent, the inherited middleware and telemetry layers, and create_harness_agent, including runtime rejection of singular values. Agent-hooks bundles remain supported as elements of a middleware sequence.
• What is the impact of these changes? This is a breaking API change for callers passing singular middleware values to agent creation or run paths; those callers must wrap middleware in a sequence. Existing sequence-based usage is unchanged. Users opting into agent-hooks install its SDK directly rather than through a core extra.
• What do you want reviewers to focus on? Confirm the packaging change does not affect the core all extra and that sequence-only enforcement remains consistent across constructor, per-run, attribute, and harness paths.

Related Issue

Fixes #7917

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 is linked to an issue and there is no other open PR for this issue (see Related Issue above).
• 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.

[github-actions]

Python Test Coverage Report •

File	Stmts	Miss	Cover	Missing
packages/core/agent_framework
_agent_hooks.py	759	149	80%	273, 310, 313–316, 318–329, 332–333, 339–340, 367, 371, 404, 406, 414–415, 421, 426, 469, 487–488, 562, 571–572, 578–579, 586, 590, 601–602, 605–606, 610, 622–623, 626, 629, 639–641, 643–644, 650, 657–665, 668–669, 676–679, 681–682, 707, 711, 739–745, 748–750, 774–781, 783–784, 803, 805, 814, 816–821, 831, 842–845, 861, 872–881, 1037–1038, 1098–1099, 1153, 1171, 1173–1174, 1202–1203, 1226, 1238–1243, 1311–1312, 1357, 1411, 1434, 1447, 1457, 1460–1464, 1487
_agents.py	462	44	90%	596, 651, 1219, 1264, 1335–1339, 1438, 1468, 1505, 1600, 1628, 1641, 1690, 1692, 1701–1706, 1711, 1713, 1719–1720, 1727, 1729–1730, 1738–1739, 1742–1744, 1754–1759, 1763, 1768, 1770
_clients.py	143	12	91%	325, 376, 539–542, 992, 994–995, 997–999
_middleware.py	451	17	96%	435, 808, 815–816, 834, 1007, 1078, 1096, 1098, 1231, 1234, 1261, 1263, 1399, 1403, 1590, 1666
observability.py	1204	87	92%	448–450, 452–453, 458–459, 464–466, 468–469, 474–475, 558, 560–561, 564, 567, 570–571, 576, 580–581, 591–592, 602–603, 614, 616–617, 620, 623, 626–627, 632, 636–637, 648–649, 660–661, 673, 837, 958–959, 1272, 1288–1289, 1495–1496, 1789, 1791, 1793, 2118–2119, 2236, 2389, 2431–2432, 2619, 2868–2869, 2873, 2913–2914, 2918, 2959–2962, 3003–3004, 3179, 3182, 3194, 3211, 3215–3216, 3219, 3225, 3245, 3321, 3355, 3457, 3694, 3696
packages/core/agent_framework/_harness
_agent.py	133	2	98%	204, 643
packages/foundry/agent_framework_foundry
_agent.py	257	18	93%	130, 133, 253, 258, 267, 378, 481–482, 506, 509, 518–519, 744–745, 748, 869, 874, 878
TOTAL	48250	4482	90%

Python Unit Test Overview

Tests	Skipped	Failures	Errors	Time
9818	36 💤	0 ❌	0 🔥	2m 50s ⏱️

[Copilot]

Pull request overview

Restores sequence-only agent middleware APIs and removes the experimental agent-hooks package extra.

Changes:

• Restricts agent middleware parameters to sequences.
• Adds runtime rejection tests for singular middleware.
• Requires direct installation of agent-hooks-sdk.

Reviewed changes

Copilot reviewed 12 out of 13 changed files in this pull request and generated 4 comments.

Show a summary per file

File	Description
python/uv.lock	Removes the agent-hooks extra.
python/pyproject.toml	Clarifies the SDK test dependency.
python/packages/core/pyproject.toml	Removes core’s agent-hooks extra.
python/packages/core/agent_framework/_agents.py	Restores sequence-only agent signatures.
python/packages/core/agent_framework/_middleware.py	Adjusts middleware runtime handling.
python/packages/core/agent_framework/observability.py	Aligns telemetry-layer signatures.
python/packages/core/agent_framework/_harness/_agent.py	Restricts harness middleware input.
python/packages/core/agent_framework/_harness/_agent.pyi	Updates harness typing.
python/packages/core/agent_framework/_agent_hooks.py	Updates SDK installation guidance.
python/packages/core/tests/core/test_middleware_with_agent.py	Tests singular-input rejection.
python/packages/core/tests/core/test_harness_agent.py	Tests harness rejection behavior.
python/packages/core/tests/core/test_agent_hooks.py	Uses bundles within sequences.
python/PACKAGE_STATUS.md	Documents direct SDK installation.

---

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

[github-actions]

MAF Automated Review — Iteration 1

Result: No findings
Scope: full PR (1 commit(s)): 612069f25526
Model: gpt-5.6-sol

Overview

The PR consistently restores sequence-only middleware annotations and removes the experimental core package extra while retaining agent-hooks bundles as sequence elements. The new tests cover ordinary singular-value rejection and valid sequence execution across direct agent and harness paths, and the packaging metadata remains internally consistent. Review identified contract-enforcement and public-factory gaps, but each is already covered by unresolved review feedback, so there are no additional publishable findings.

Reviewed the supplied pull-request change set across correctness, security/reliability, architecture, and failure behavior.
No publishable findings remained after source verification for this scope.