[BREAKING] Python: Adjust magentic event types raised. No need for custom events.

[moonbox3]

Motivation and Context

Right now there are custom even types raised from the magentic orchestration pattern. These aren't needed, and aren't actually picked up/raised to the caller while running the workflow as an agent. Since the orchestration pattern uses agents, we should simply yield the underlying agent types to the caller. To help distinguish what is going on in the magentic flow, metadata around the event type is added to the AgentRunResponseUpdate.

Caution

No rush in merging this - fine to do after Ignite because it's breaking.

Important

Once this is in, I will update the learn site docs.

Description

• Closes Python: running Magentic orchestration as_agent() doesn't raise custom events #2213

Contribution Checklist

• The code builds clean without any errors or warnings
• The PR follows the Contribution Guidelines
• All unit tests pass, and I have added new tests where possible
• Is this a breaking change? If yes, add "[BREAKING]" prefix to the title of the PR.

[Copilot]

Pull Request Overview

This PR refactors the Magentic orchestration pattern to eliminate custom event types (MagenticOrchestratorMessageEvent, MagenticAgentDeltaEvent, MagenticAgentMessageEvent, MagenticFinalResultEvent) and instead emit standard AgentRunUpdateEvent objects with metadata to distinguish event types. This allows workflows to work seamlessly as agents and unifies the event handling pattern across the framework.

Key changes:

• Replaced custom Magentic event types with AgentRunUpdateEvent containing metadata fields (magentic_event_type, orchestrator_message_kind, agent_id)
• Exported new constants (MAGENTIC_EVENT_TYPE_AGENT_DELTA, MAGENTIC_EVENT_TYPE_ORCHESTRATOR, ORCH_MSG_KIND_*) for event type identification
• Updated sample code to use metadata-based event handling instead of type checking custom events

Reviewed Changes

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

Show a summary per file

File	Description
python/packages/core/agent_framework/_workflows/_magentic.py	Core implementation: removes custom event classes and emits AgentRunUpdateEvent with metadata; updates documentation
python/packages/core/agent_framework/_workflows/init.py	Exports new event type constants and removes custom event types from public API
python/packages/core/agent_framework/_workflows/init.pyi	Updates type stubs to reflect new constants and removed event types
python/packages/core/agent_framework/_workflows/_agent.py	Updates documentation to clarify that workflow-internal events are ignored
python/packages/core/tests/workflow/test_magentic.py	Updates test to handle AgentRunUpdateEvent instead of MagenticAgentMessageEvent; re-enables previously skipped tests
python/samples/getting_started/workflows/orchestration/magentic_human_plan_update.py	Updates sample to use AgentRunUpdateEvent with metadata checks instead of custom event types
python/samples/getting_started/workflows/agents/magentic_workflow_as_agent.py	Simplifies sample to demonstrate workflow-as-agent pattern using metadata-based event handling

[markwallace-microsoft]

Python Test Coverage Report •

File	Stmts	Miss	Cover	Missing
packages/core/agent_framework/_workflows
_agent.py	232	40	82%	55, 63–69, 97–98, 248, 288–291, 297, 303, 307–308, 311–317, 321–322, 361, 368, 374–375, 381, 393, 425, 432, 453, 460, 464, 475
_magentic.py	888	262	70%	67–76, 81, 85–96, 269, 274, 291, 293, 308, 316–325, 403, 407, 421, 427, 442, 522, 535, 552, 561–562, 564–566, 568, 579, 629, 646–650, 653–657, 737–740, 743–747, 749–751, 758, 797, 844, 880–882, 884, 1032, 1034–1035, 1043, 1069–1070, 1079, 1088–1090, 1109, 1120, 1130–1131, 1133–1134, 1153, 1206, 1226, 1229, 1258, 1261, 1269–1273, 1279, 1307–1309, 1311, 1313, 1321–1324, 1326, 1330–1331, 1334–1337, 1339–1340, 1346–1348, 1351–1352, 1357–1358, 1366, 1374, 1389, 1401, 1413–1416, 1445–1446, 1451–1453, 1484, 1510, 1524, 1540, 1556, 1626, 1632–1633, 1647, 1649, 1652, 1654–1655, 1658–1659, 1663, 1666, 1687, 1724–1725, 1727, 1731–1733, 1792, 1797–1798, 2124–2125, 2129, 2144, 2149, 2152, 2206, 2217, 2228–2230, 2243–2244, 2249, 2260–2262, 2273–2275, 2287–2294, 2296–2297, 2305, 2313–2314, 2316–2318, 2320–2323, 2327–2335, 2339–2340, 2343–2347, 2349–2350, 2352–2354, 2356–2359, 2361–2363, 2365–2366, 2368–2370, 2385–2388, 2399–2402, 2414–2417, 2421
TOTAL	14671	2103	85%

Python Unit Test Overview

Tests	Skipped	Failures	Errors	Time
2039	126 💤	0 ❌	0 🔥	40.312s ⏱️