Alexlavaee/feature/handoff workflow

[lavaman131]

Short Description

Replaced SupervisorWorkflowBuilder with extended HandoffBuilder with custom functionality:

Credits to Evan Mattson for design idea for set_coordinator.

workflow = (
        AutoHandoffBuilder(
            name="support",
            # Remove the coordinator from the participant list no matter what
            participants=[replacement, delivery, billing],
        )
        .set_coordinator(AgentProtocol | BaseChatClient)
        .build()
    )

Long Description

This pull request introduces a new workflow builder, AutoHandoffBuilder, which automatically creates a coordinator agent for multi-agent workflows, replacing the previous supervisor-based pattern. It updates documentation, workflow construction, and prompt templates to reflect this new pattern, streamlining the setup of orchestrated agent workflows and reducing boilerplate. Additionally, it removes the supervisor agent and related structured output, and adds support for the microsoft-learn tool for accessing Microsoft documentation.

Major workflow architecture update:

• Added AutoHandoffBuilder in src/spec_to_agents/workflow/auto_handoff.py, which auto-generates a coordinator agent from participant descriptions if not set explicitly, simplifying workflow setup and eliminating manual coordinator configuration.
• Updated build_event_planning_workflow in src/spec_to_agents/workflow/core.py to use AutoHandoffBuilder instead of the supervisor pattern, reflecting a coordinator-centric architecture and updating documentation and usage examples accordingly. [1] [2]

Prompt and agent changes:

• Added a new coordinator system prompt template in src/spec_to_agents/prompts/coordinator.py and removed the supervisor system prompt and related structured output from src/spec_to_agents/prompts/supervisor.py and src/spec_to_agents/models/messages.py. [1] [2] [3]

Documentation and tool updates:

• Added documentation for the microsoft-learn tool in AGENTS.md and CLAUDE.md, specifying its use for official Microsoft documentation and clarifying when to use it over deepwiki.
• Registered the microsoft-learn MCP server in .mcp.json for API access.

Exports and imports:

• Updated workflow module exports to include AutoHandoffBuilder and removed supervisor-related imports. [1] [2] [3]

[1] [2] [3] [4] [5] [6] [7] [8] [9] [10]

[Copilot]

Pull Request Overview

This PR migrates the event planning workflow from a custom SupervisorWorkflowBuilder implementation to AutoHandoffBuilder, which extends Microsoft Agent Framework's HandoffBuilder with automatic coordinator creation. The migration eliminates custom routing logic in favor of framework-native handoff patterns while preserving the auto-configuration convenience.

Key changes:

• Introduces AutoHandoffBuilder subclass that automatically creates a coordinator agent from participant descriptions when .set_coordinator() is not called
• Removes SupervisorWorkflowBuilder, SupervisorOrchestratorExecutor, and SupervisorDecision model (no longer needed)
• Updates specialist prompts to use natural conversational output instead of structured JSON responses
• Adapts console.py to handle HandoffUserInputRequest instead of HumanFeedbackRequest

Reviewed Changes

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

Show a summary per file

File	Description
src/spec_to_agents/workflow/auto_handoff.py	New AutoHandoffBuilder class extending HandoffBuilder with automatic coordinator creation logic
src/spec_to_agents/prompts/coordinator.py	New coordinator system prompt template for auto-generated coordinators using handoff tools
src/spec_to_agents/workflow/core.py	Refactored to use AutoHandoffBuilder with simplified fluent API
src/spec_to_agents/workflow/supervisor.py	Deleted - replaced by AutoHandoffBuilder and framework-native patterns
src/spec_to_agents/models/messages.py	Removed SupervisorDecision model, cleaned up imports
src/spec_to_agents/prompts/*.py	Updated specialist prompts to use conversational output and handoff_to_coordinator calls
src/spec_to_agents/console.py	Updated to use HandoffUserInputRequest instead of HumanFeedbackRequest
tests/workflow/test_auto_handoff.py	New tests for AutoHandoffBuilder functionality
CLAUDE.md, AGENTS.md, .mcp.json	Documentation updates and added microsoft-learn MCP server
specs/handoff-workflow.md	Comprehensive ExecPlan documenting the migration strategy and implementation details

[Copilot]

The display_human_feedback_request function is still defined in src/spec_to_agents/utils/display.py (lines 117-185) but is no longer imported or used. Consider removing the unused function from display.py to avoid confusion and maintain code cleanliness.