Principle:Microsoft Agent framework Agent Executor Wrapping

Overview

This principle describes the pattern of wrapping an Agent as a workflow executor node using the AgentExecutor class. AgentExecutor serves as the bridge between the agent system and the workflow engine, enabling agents to participate as first-class nodes in graph-based workflows.

By encapsulating an agent inside an Executor-compatible wrapper, the workflow engine can invoke agents through a uniform interface without knowledge of the underlying agent implementation. This decouples workflow orchestration from agent internals and allows heterogeneous agents to be composed into complex, multi-step workflows.

Motivation

In a graph-based workflow system, each node must conform to the Executor protocol: it must accept well-defined input types and produce a standardized output. Agents, however, operate on their own abstractions (messages, threads, tool calls). The Agent Executor Wrapping principle resolves this impedance mismatch by:

Accepting multiple input types and normalizing them into a form the agent understands.
Producing a uniform output type (AgentExecutorResponse) that downstream nodes can consume.
Managing the agent's conversational thread transparently within the workflow lifecycle.

Input / Output Contract

**AgentExecutor I/O Contract**
Direction	Type	Description
Input	`str`	Plain text prompt; automatically wrapped into a message for the agent.
Input	`Message`	A single message object passed directly to the agent.
Input	`list[Message]`	A sequence of messages representing a conversation fragment.
Input	`AgentExecutorRequest`	Structured request carrying a message payload plus optional thread context.
Input	`AgentExecutorResponse`	A response from a prior executor, enabling chaining of executor nodes.
Output	`AgentExecutorResponse`	Standardized response containing `.executor_id`, `.agent_response`, and `.full_conversation`.

Design Constraints

Single Responsibility -- AgentExecutor is solely responsible for adapting the Executor interface to the Agent interface. It must not contain business logic.
Thread Transparency -- The conversational thread (if any) is managed by AgentExecutor on behalf of the agent. Callers may optionally supply an AgentThread.
Input Polymorphism -- Each accepted input type is handled by a dedicated @handler method, ensuring clean dispatch and avoiding type-checking conditionals in a single handler.
Output Uniformity -- Regardless of which input type triggers execution, the output is always an AgentExecutorResponse. This guarantees that downstream nodes see a consistent contract.

Relationship to Workflow Engine

The following diagram illustrates how AgentExecutor fits into the workflow graph:

  [Upstream Node]
        |
        v
  +---------------------+
  |   AgentExecutor     |
  |  (Executor node)    |
  |                     |
  |  wraps: Agent       |
  |  thread: AgentThread|
  +---------------------+
        |
        v  AgentExecutorResponse
  [Downstream Node]

The WorkflowBuilder treats AgentExecutor identically to any other Executor subclass, which means agents can be freely mixed with tool executors, branching nodes, and aggregation nodes within the same workflow graph.

Metadata

Property	Value
Domains	Workflow_Engine, Agent_Architecture
Principle ID	`Microsoft_Agent_framework_Agent_Executor_Wrapping`
Status	Active

Page Connections

Double-click a node to navigate. Hold to expand connections.

Principle

Implementation

Heuristic

Environment