Python: WorkflowBuilder registry

[Tao Chen (TaoChenOSU)]

Motivation and Context

Closing #429

Description

Add support for providing factories to create executors and agents to the workflow builder to allow the workflow builder to create isolated workflow instances.

1. To register an executor factory, use builder.register_executor().
2. To register an agent factory, use builder.register_agent().
3. Full backward compatibility with warnings to users that they should use the factory pattern.
4. Update samples.

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.

[Evan Mattson (moonbox3)]

Also, is this truly breaking? It should be additive, right?

[Mark Wallace (markwallace-microsoft)]

Python Test Coverage Report •

File	Stmts	Miss	Cover	Missing
packages/core/agent_framework
observability.py	609	101	83%	238, 264–266, 268, 270–274, 282–283, 288–289, 294–299, 322–324, 326–327, 333, 417, 427, 449, 455, 474–476, 484–486, 508–510, 520–522, 655, 657, 744–748, 751–755, 764–767, 777–780, 782, 1049, 1127–1129, 1199–1201, 1359, 1367, 1371, 1375, 1381, 1383, 1385, 1393, 1403, 1431–1432, 1445–1448, 1467–1469, 1471–1474, 1476–1477, 1481, 1484, 1542, 1558, 1562, 1696, 1698
packages/core/agent_framework/_workflows
_edge.py	218	26	88%	36, 58–59, 61, 413–414, 419, 423–428, 430–432, 542, 656, 663–665, 712, 740, 766, 820, 834
_validation.py	145	6	95%	85, 132, 153, 247, 328, 331
_workflow.py	249	18	92%	94, 264–266, 268–269, 287, 311, 313, 410, 659, 693, 698, 701, 720–722, 787
_workflow_builder.py	286	38	86%	259, 596, 694, 700–701, 798–799, 805, 808, 810, 812, 819, 822–826, 828, 892, 959, 969, 1028–1029, 1164, 1178–1185, 1187, 1190, 1192–1194, 1202
TOTAL	16180	2538	84%

Python Unit Test Overview

Tests	Skipped	Failures	Errors	Time
2312	130 💤	0 ❌	0 🔥	58.062s ⏱️

[Copilot]

Pull request overview

This PR introduces a factory-based registration pattern for executors and agents in the WorkflowBuilder, enabling lazy initialization and isolated workflow instances. Key changes include new register_executor() and register_agent() methods, deprecation warnings for direct instance addition, and comprehensive sample updates demonstrating the new pattern.

• Factory-based registration via register_executor() and register_agent() for deferred instantiation
• Backward compatibility maintained with deprecation warnings on add_agent() and direct executor addition
• All 25+ sample files migrated to use the factory pattern
• Comprehensive test coverage for new registration patterns
• New sample file (step4_using_factories.py) demonstrating best practices

Reviewed changes

Copilot reviewed 33 out of 33 changed files in this pull request and generated 16 comments.

Show a summary per file

File	Description
_workflow_builder.py	Implements executor/agent factory registration with deferred edge resolution
_workflow.py	Simplifies start executor handling to require Executor instance
_validation.py	Updates validation to accept Executor instance instead of union type
_edge.py	Allows Case and Default targets to be strings for deferred resolution
test_workflow_builder.py	Adds 13 new tests for factory registration patterns
Sample files (25+)	Migrated to factory pattern with agent/executor factory functions