Python: Optimize shared serialization paths

[eavanvalkenburg]

Motivation & Context

Serialization is a hot path for messages, telemetry, and protocol payloads. Repeated runtime structural protocol checks and overlapping JSON-safe conversion implementations added avoidable CPU time and allocations.

This consolidates common conversion paths while preserving duck-typed serialization support and package-specific wire-format behavior.

Description & Review Guide

• What are the major changes? Cache structural serialization-protocol detection by concrete type; add primitive and container fast paths; reuse the shared detector in observability; consolidate AG-UI on core's optimized JSON-safe converter; bypass redundant validation for typed AG-UI interrupts and resume entries; and document how packages should reuse these paths.
• What is the impact of these changes? Representative local benchmarks improved core serialization from 109.35 to 45.50 microseconds per call (about 58%), round trips from 106.50 to 75.48 microseconds (about 29%), and nested AG-UI JSON-safe conversion from 1325.54 to 1032.29 microseconds per call (about 22%). Existing payload shapes and provider-specific JSON boundaries remain unchanged.
• What do you want reviewers to focus on? Please focus on compatibility for duck-typed serializers, container subclasses, and AG-UI protocol aliases, plus whether the coding-standard guidance draws the right boundary between shared conversion and provider-specific wire formatting.

Related Issue

Fixes #7164

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/ag-ui/agent_framework_ag_ui
_http_service.py	107	9	91%	22, 26, 44–45, 59, 62, 72, 110, 113
_utils.py	89	5	94%	61, 65–66, 69, 89
packages/core/agent_framework
_serialization.py	173	12	93%	355–356, 542, 559, 569, 637, 677–678, 682–683, 685, 687
observability.py	1010	80	92%	423, 425–426, 429, 432, 435–436, 441–442, 448–449, 455–456, 463, 465–466, 469, 472, 475–476, 481–482, 488–489, 495–496, 503, 680–681, 891, 895–897, 899, 907–908, 912, 956, 958, 969–971, 973–975, 979, 987, 1111–1112, 1347, 1626–1627, 1738, 1888, 1931–1932, 2121, 2349–2350, 2354, 2394–2395, 2399, 2440–2443, 2484–2485, 2636, 2639, 2651, 2668, 2672–2673, 2676, 2682, 2802, 3019, 3021
TOTAL	44599	5213	88%

Python Unit Test Overview

Tests	Skipped	Failures	Errors	Time
9047	33 💤	0 ❌	0 🔥	2m 27s ⏱️

[Copilot]

Pull request overview

This PR optimizes Python serialization hot paths by consolidating JSON-safe conversion and reducing repeated structural protocol checks, while keeping existing payload shapes and provider-specific wire-format boundaries intact.

Changes:

• Adds cached structural detection for framework serialization protocol support and introduces scalar/container fast paths in core serialization utilities.
• Reuses the shared protocol detector in core observability tool-definition serialization and centralizes AG-UI’s JSON-safe conversion on core’s make_json_safe.
• Bypasses redundant validation/normalization for typed AG-UI Interrupt and ResumeEntry inputs, and updates coding guidance + adds a regression test for structural (duck-typed) protocol implementations.

Reviewed changes

Copilot reviewed 6 out of 6 changed files in this pull request and generated 1 comment.

Show a summary per file

File	Description
python/packages/core/agent_framework/_serialization.py	Adds cached protocol detection and fast paths in SerializationMixin.to_dict and make_json_safe.
python/packages/core/agent_framework/observability.py	Switches tool-definition serialization to use the shared structural protocol detector.
python/packages/ag-ui/agent_framework_ag_ui/_utils.py	Removes package-local make_json_safe and reuses core’s optimized converter.
python/packages/ag-ui/agent_framework_ag_ui/_http_service.py	Adds fast-path serialization for typed Interrupt / ResumeEntry via model_dump(by_alias=True).
python/packages/core/tests/core/test_serializable_mixin.py	Adds coverage for nested duck-typed structural protocol serialization without requiring the mixin.

[github-actions]

Automated Code Review

Reviewers: 5 | Confidence: 77% | Result: All clear

Reviewed: Correctness, Security Reliability, Test Coverage, Failure Modes, Design Approach

---

Automated review by eavanvalkenburg's agents