Principle:Microsoft Agent framework Workflow Agent Wrapping

Property	Value
Principle Name	Workflow Agent Wrapping
SDK	Microsoft Agent Framework
Repository	Microsoft Agent Framework
Source Reference	python/packages/core/agent_framework/_workflows/_workflow.py:L841-866
Import	from agent_framework._workflows._workflow import Workflow
Domains	Agent_Architecture, Multi_Agent_Systems

Overview

Workflow Agent Wrapping is the principle of exposing a multi-step workflow as a single agent through the Workflow.as_agent() method. This allows orchestrated workflows -- composed of multiple executors, edges, and branching logic -- to satisfy the SupportsAgentRun protocol so they can be used wherever a single agent interface is expected.

Description

In the Microsoft Agent Framework, workflows are directed graphs of executors that process data through a series of connected steps. While powerful, workflows expose a fundamentally different interface from agents: they operate on typed executor inputs and emit WorkflowEvent objects, whereas consumers of agents expect the standard run() contract with str, Message, or list[Message] inputs and AgentResponse / AgentResponseUpdate outputs.

Workflow Agent Wrapping bridges this gap by creating a WorkflowAgent instance that:

1. Normalizes agent-facing inputs to workflow-facing inputs: Converts the flexible input types (str, Message, list[str | Message]) into a uniform list[Message] that the workflow's start executor can consume.
2. Translates workflow events to agent responses: Converts WorkflowEvent output events and request-info events into AgentResponse and AgentResponseUpdate objects.
3. Preserves the full agent contract: Supports streaming, non-streaming, thread-based multi-turn conversations, and checkpoint-based resumption.

Start Executor Constraint

The workflow's start executor must accept list[Message] as one of its input types. This constraint is enforced at initialization time: if the start executor cannot handle list[Message], a ValueError is raised. This ensures that the normalization bridge between the agent interface and the workflow graph is always valid.

Composability

This principle enables hierarchical composition of multi-agent systems. A sequential workflow of writer -> reviewer agents can be wrapped as a single WorkflowAgent and then used as a participant inside another orchestration (e.g., a group chat or concurrent fan-out). The outer orchestration sees only a standard agent interface, with no awareness of the internal workflow topology.

Event Filtering

Not all workflow events are surfaced through the agent interface. Only events with type='output' and type='request_info' are converted to agent responses. Internal workflow events (such as executor transitions, state updates, and edge evaluations) are filtered out, keeping the agent interface clean and focused on meaningful results.

Theoretical Basis

Workflow Agent Wrapping applies the Adapter Pattern from object-oriented design. The WorkflowAgent class acts as an adapter that translates between two incompatible interfaces:

Aspect	Agent Interface (Target)	Workflow Interface (Adaptee)
Input	Message | list[str | Message]	list[Message] (via start executor)
Output	AgentResponse / AgentResponseUpdate	WorkflowEvent stream
Execution	await agent.run(...)	await workflow.run(message=...)
Identity	SupportsAgentRun protocol	Workflow graph object

The normalization step follows the Facade Pattern, presenting a simplified interface to the caller while hiding the complexity of message conversion, event filtering, and response aggregation that occurs internally.

Input Normalization Rules

The WorkflowAgent normalizes incoming messages according to the following rules:

Input Type	Normalized Output	Description
str	[Message(role="user", text=input)]	A plain string is wrapped as a single user message.
Message	[message]	A single Message is placed into a one-element list.
Message]	list[Message]	Each string element is converted to a user Message; Message elements pass through unchanged.
None	[]	No input yields an empty list (used for checkpoint resumption).

Related Pages

• Implementation:Microsoft_Agent_framework_Workflow_As_Agent

Sources

Type	Name	URL
Repo	Microsoft Agent Framework	https://github.com/microsoft/agent-framework