agent-framework/python/samples/getting_started/orchestrations/README.md

Orchestration Getting Started Samples

Installation

The orchestrations package is included when you install agent-framework (which pulls in all optional packages):

pip install agent-framework

Or install the orchestrations package directly:

pip install agent-framework-orchestrations

Orchestration builders are available via the agent_framework.orchestrations submodule:

from agent_framework.orchestrations import (
    SequentialBuilder,
    ConcurrentBuilder,
    HandoffBuilder,
    GroupChatBuilder,
    MagenticBuilder,
)

Samples Overview

Sample	File	Concepts
Concurrent Orchestration (Default Aggregator)	concurrent_agents.py	Fan-out to multiple agents; fan-in with default aggregator returning combined Messages
Concurrent Orchestration (Custom Aggregator)	concurrent_custom_aggregator.py	Override aggregator via callback; summarize results with an LLM
Concurrent Orchestration (Custom Agent Executors)	concurrent_custom_agent_executors.py	Child executors own Agents; concurrent fan-out/fan-in via ConcurrentBuilder
Group Chat with Agent Manager	group_chat_agent_manager.py	Agent-based manager using with_orchestrator(agent=) to select next speaker
Group Chat Philosophical Debate	group_chat_philosophical_debate.py	Agent manager moderates long-form, multi-round debate across diverse participants
Group Chat with Simple Function Selector	group_chat_simple_selector.py	Group chat with a simple function selector for next speaker
Handoff (Simple)	handoff_simple.py	Single-tier routing: triage agent routes to specialists, control returns to user after each specialist response
Handoff (Autonomous)	handoff_autonomous.py	Autonomous mode: specialists iterate independently until invoking a handoff tool using .with_autonomous_mode()
Handoff with Code Interpreter	handoff_with_code_interpreter_file.py	Retrieve file IDs from code interpreter output in handoff workflow
Magentic Workflow (Multi-Agent)	magentic.py	Orchestrate multiple agents with Magentic manager and streaming
Magentic + Human Plan Review	magentic_human_plan_review.py	Human reviews/updates the plan before execution
Magentic + Checkpoint Resume	magentic_checkpoint.py	Resume Magentic orchestration from saved checkpoints
Sequential Orchestration (Agents)	sequential_agents.py	Chain agents sequentially with shared conversation context
Sequential Orchestration (Custom Executor)	sequential_custom_executors.py	Mix agents with a summarizer that appends a compact summary

Tips

Magentic checkpointing tip: Treat MagenticBuilder.participants keys as stable identifiers. When resuming from a checkpoint, the rebuilt workflow must reuse the same participant names; otherwise the checkpoint cannot be applied and the run will fail fast.

Handoff workflow tip: Handoff workflows maintain the full conversation history including any Message.additional_properties emitted by your agents. This ensures routing metadata remains intact across all agent transitions. For specialist-to-specialist handoffs, use .add_handoff(source, targets) to configure which agents can route to which others with a fluent, type-safe API.

Sequential orchestration note: Sequential orchestration uses a few small adapter nodes for plumbing:

• input-conversation normalizes input to list[Message]
• to-conversation:<participant> converts agent responses into the shared conversation
• complete publishes the final output event (type='output')

These may appear in event streams (executor_invoked/executor_completed). They're analogous to concurrent's dispatcher and aggregator and can be ignored if you only care about agent activity.

Environment Variables

• AzureOpenAIChatClient: Set Azure OpenAI environment variables as documented here.

• OpenAI (used in some orchestration samples):

  • OpenAIChatClient env vars
  • OpenAIResponsesClient env vars