Principle:Microsoft Autogen Swarm Execution
| Knowledge Sources | |
|---|---|
| Domains | Multi-Agent Systems, Streaming Execution, Event-Driven Architecture, Swarm Workflows |
| Last Updated | 2026-02-11 00:00 GMT |
Overview
Swarm execution is the runtime process of driving a swarm conversation forward by streaming agent events, chat messages, and handoff transitions until a termination condition is met.
Description
Once a swarm team is assembled, it must be executed to produce results. Swarm execution follows the streaming event model: rather than waiting for the entire conversation to complete, the system yields individual events as they occur. This provides real-time visibility into the agent interactions, including the critical HandoffMessage events that signal agent transitions.
The execution flow produces a stream of heterogeneous event types:
- BaseAgentEvent: Internal agent events such as tool calls, model client streaming chunks, and other agent-level activity. These provide fine-grained visibility into what each agent is doing.
- BaseChatMessage: Messages that form the conversation thread. This includes TextMessage (regular agent responses), HandoffMessage (agent transition signals), and ToolCallSummaryMessage (results of tool executions).
- TaskResult: The final item in the stream, containing the complete message history and the stop reason. This is always the last item yielded.
The HandoffMessage is the event type unique to swarm execution. Unlike TextMessage, a HandoffMessage does not contain a conversational response; instead, it carries:
- The source agent that initiated the transfer.
- The target agent that should receive control.
- A content string providing context for the transfer.
Consumers of the stream can use HandoffMessage events to track the flow of control through the swarm, build audit trails, or update user interfaces showing which agent is currently active.
Usage
Use swarm streaming execution when:
- You need real-time visibility into agent interactions as they happen.
- Your application requires progressive UI updates (e.g., showing which agent is speaking, displaying partial responses).
- You need to detect and react to handoff events for logging, monitoring, or UI purposes.
- You want to combine swarm execution with Console output for debugging.
- You are building a system that needs the final TaskResult along with the event stream.
Theoretical Basis
Swarm execution implements the async generator pattern for event streaming. The execution model can be described as a producer-consumer pipeline:
Swarm Execution Pipeline:
Producer (run_stream):
1. Convert task input to message(s):
- str -> TextMessage(content=task, source="user")
- BaseChatMessage -> used directly
- Sequence[BaseChatMessage] -> used as list
- None -> continue from previous state
2. Initialize runtime and group chat manager
3. LOOP until termination:
a. Manager selects current speaker (based on last HandoffMessage)
b. Speaker agent processes conversation context
c. Agent produces events:
- ToolCallEvent, ModelClientStreamingChunkEvent (agent events)
- TextMessage (regular response)
- HandoffMessage (transition signal)
d. Each event is YIELDED to the consumer immediately
e. Manager checks termination conditions against new messages
f. If terminated: yield StopMessage
4. Collect all non-streaming messages into TaskResult
5. YIELD TaskResult as final item
Consumer (caller):
async for event in team.run_stream(task="..."):
if isinstance(event, TaskResult):
# Final result with complete message history
elif isinstance(event, HandoffMessage):
# Agent transition detected
else:
# Regular agent event or chat message
Key properties:
- ModelClientStreamingChunkEvent is yielded but NOT included in TaskResult.messages
- TaskResult is ALWAYS the last item in the stream
- The team is stateful: subsequent run_stream() calls continue from where the last left off
- CancellationToken can abort execution but may leave the team in inconsistent state
The streaming model provides backpressure-free observation: consumers receive events as they are produced without affecting the execution speed of the agents. This is essential for UI applications that need to render progress without blocking the conversation.