.NET: [BREAKING] feat: Improve Agent hosting inside Workflows

[Jacob Alber (lokitoth)]

Motivation and Context

Our initial implementation of hosting Agents in Workflows unblocked a number of scenarios but had some rough edges, resulting in the need to create custom Executors for, e.g., implementing Orchestrations. This leads to accumulating inconsistencies in behaviour as fixes and changes come in, resulting in issues like #2888.

In addition, there is a lack of support for HIL in both cases, resulting in custom-built support for hosting Agents in Declarative Workflows.

Description

• Adds support for HIL and uninvoked FunctionCalls for hosted agents
• Adds configurability for emitting streaming updates and the final combined response
• Adds support for forwarding the incoming conversation to make supporting things like Handoffs easier
• Adds support for overwriting other agents' ChatRole when invoking hosted agents
• Builds out internal-only support for direct ExternalRequest "raising" by Executor

Breaking:

• Changes AIAgentBinding to contain AIAgentHostOptions rather than a bool

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 improves the Agent hosting capabilities within Workflows by introducing comprehensive support for Human-in-the-Loop (HIL) scenarios, uninvoked function calls, and configurable execution behavior. The changes enable more flexible agent orchestration patterns and better control over message flow and event emission.

Key Changes:

• Introduces AIAgentHostOptions to provide fine-grained configuration for agent hosting (replacing the previous boolean flag)
• Adds support for intercepting and handling UserInputRequestContent and FunctionCallContent through dynamic port registration
• Implements role reassignment capabilities to allow agents to see other agents' messages as user messages

Reviewed changes

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

Show a summary per file

File	Description
AIAgentHostOptions.cs	New configuration class for agent hosting behavior with properties for event emission, request interception, role reassignment, and message forwarding
AIAgentHostExecutor.cs	Major refactor to support request interception, port handlers, turn continuation, and configurable event emission
AIAgentBinding.cs	Breaking change - now accepts AIAgentHostOptions instead of a boolean, maintains backward compatibility with overload
RouteBuilder.cs	Adds AddPortHandler method to support dynamic port registration and routing
Executor.cs	Adds Configure method to enable port handler registration via IExternalRequestContext
ChatProtocolExecutor.cs	Adds AutoSendTurnToken option and ProcessTurnMessagesAsync helper method
EdgeMap.cs	Adds TryRegisterPort method for dynamic port registration at runtime
InProcessRunnerContext.cs	Splits binding into BindExternalRequestContext and BindWorkflowContext for proper lifecycle management
AIContentExternalHandler.cs	New helper class for managing pending requests and responses for AIContent-based request/response patterns
RequestPortExtensions.cs	New extension methods for validating and processing ExternalResponse messages
PortBinding.cs	New class representing the binding between a RequestPort and its sink
AgentWorkflowBuilder.cs	Updated to use new AIAgentHostOptions with proper role reassignment and message forwarding
AggregateTurnMessagesExecutor.cs	Renamed from CollectChatMessagesExecutor for clarity
TestRequestAgent.cs	New comprehensive test agent supporting function calls and user input requests
TestReplayAgent.cs	Extracted from SpecializedExecutorSmokeTests for reuse
RoleCheckAgent.cs	New test agent for validating role reassignment behavior
AIAgentHostExecutorTests.cs	Comprehensive test coverage for new agent hosting features
DynamicRequestPortTests.cs	Tests for dynamic port registration and message delivery