Principle:Microsoft Autogen Team Execution
| Knowledge Sources | |
|---|---|
| Domains | Multi-Agent Systems, Async Execution, Stream Processing, AI Agents, Result Aggregation |
| Last Updated | 2026-02-11 00:00 GMT |
Overview
Team execution is the process of running a configured multi-agent team on a task, collecting the messages produced by agents during the conversation, and returning a structured result that includes the conversation history and the reason for termination.
Description
After agents are created, termination conditions defined, and a team assembled with an orchestration strategy, the final step is execution -- actually running the team on a task and consuming its output. Team execution bridges the gap between configuration and results.
Team execution involves several concerns:
- Task injection: Converting a user-provided task (which may be a plain string, a structured message, or a sequence of messages) into the initial messages that seed the conversation.
- Lifecycle management: Initializing the runtime, registering agents, starting the conversation loop, and cleaning up after completion. This includes ensuring the runtime is properly started and stopped, and that termination conditions are reset for potential re-use.
- Output modes: Supporting both batch execution (run the full conversation and return the final result) and streaming execution (yield each message as it is produced, then yield the final result). Streaming is essential for user-facing applications where responsiveness matters.
- Result aggregation: Collecting all messages produced during the conversation into a structured result that includes the full message history and the stop reason (termination condition text or max turns reached).
- Console rendering: For development and debugging, rendering the stream of messages to a terminal in a human-readable format with agent names, message content, and optional token usage statistics.
- Cancellation: Supporting cancellation tokens that allow external code to abort a running team, useful for timeouts and user-initiated cancellation.
- Resumption: Teams can be run multiple times. After a run completes, calling run again without a task continues the conversation from where it left off.
The distinction between run() and run_stream() reflects a fundamental design pattern in async systems: pull-based vs. push-based consumption. run() internally uses run_stream() and buffers the entire conversation, returning only the final result. run_stream() yields messages as they are produced, enabling real-time UI updates, logging, and progressive rendering.
Usage
Team execution is the final step in every multi-agent workflow. Use it when:
- You have a fully configured team and want to run it on a specific task.
- You need real-time visibility into the conversation as it progresses (use streaming).
- You want to collect the final result for downstream processing (use batch).
- You need to render the conversation to a terminal during development (use Console).
- You need to support cancellation for long-running conversations.
- You want to run multiple rounds of conversation on the same team.
Theoretical Basis
Team execution follows the Producer-Consumer pattern from concurrent systems design. The team (producer) generates a stream of messages, and the consumer (application code, Console renderer, or run() aggregator) processes them.
The execution flow can be described as:
FUNCTION run(team, task, cancellation_token):
1. Convert task to initial messages
2. Start the async message stream via run_stream
3. Iterate over the stream, collecting all items
4. The last item in the stream is the TaskResult
5. Return the TaskResult
FUNCTION run_stream(team, task, cancellation_token):
1. Convert task to initial messages (string -> TextMessage, etc.)
2. If not initialized, set up runtime:
a. Register participant agents with unique topic types
b. Register group chat manager
c. Set up pub/sub subscriptions
d. Start the runtime
3. If task messages exist and output_task_messages is True:
a. Yield each task message to the stream
4. Publish task messages to the group topic
5. LOOP:
a. Await next message from the output queue
b. If message is a GroupChatTermination:
- Construct TaskResult with collected messages and stop reason
- Yield the TaskResult
- Reset termination condition
- BREAK
c. Otherwise:
- Yield the message (agent event or chat message)
- Add to collected messages list
6. Stop the runtime
FUNCTION Console(stream, no_inline_images, output_stats):
1. Iterate over the message stream
2. For each message:
a. Format agent name as header
b. Render message content (text, tool calls, images)
c. Optionally display inline images (iTerm2 support)
d. Print to terminal
3. If output_stats is True:
a. Aggregate token usage across all messages
b. Print summary statistics
4. Return the final TaskResult or Response
The async generator pattern used by run_stream() enables backpressure -- the producer only generates the next message when the consumer is ready to receive it. This prevents memory issues in long conversations and allows the consumer to control the pace of execution.
The Console function follows the Decorator pattern -- it wraps the stream, renders each message as a side effect, and passes through the final result unchanged. This allows Console to be composed with any stream-producing method without modifying the underlying behavior.
A key design choice is that run() is implemented in terms of run_stream(), not the other way around. This ensures there is a single source of truth for the execution logic, and the batch mode is simply a convenience wrapper that exhausts the stream and returns the final item.