Azure-Samples / Azure-Samples/foundry-hosted-agents-workshop
[Feature] Showcase more multi-agent orchestration flavors (group chat, handoff, workflow, magentic)
- Dominant language
- Python
- Stars
- 7
- Forks
- 7
- Avg merge
- 2h 59m
- Merged PRs (30d)
- 3
Description
## Problem or opportunity
The workshop teaches two multi-agent shapes today: **runtime handoff** in Step 7 (`HandoffBuilder` exposed via `workflow.as_agent()`) and a **workflow** in Step 8 (`WorkflowBuilder`). The Agent Framework ships several first-class orchestration patterns, and Step 7 already name-drops `SequentialBuilder` / `ConcurrentBuilder` in its concept section — but participants never see them run, nor the higher-level **group chat** and **magentic** orchestrators. Learners finish the workshop knowing *handoff vs. workflow* but without a mental map of the full menu or when to reach for each.
There's also a concrete, recently-fixed footgun that argues for making these patterns explicit: hosting a default `HandoffBuilder` as an agent parks each turn in `IDLE_WITH_PENDING_REQUESTS`, so a **follow-up question fails** with `Unexpected content type while awaiting request info responses` unless you add a `termination_condition` + route silently. Each orchestration flavor has its own hosting nuances like this, and a short tour would surface them.
## Proposed improvement
Add a concise tour (a new optional step, or an appendix / expandable section off Step 7's "Handoff vs. workflow" callout) that shows each native orchestration flavor against the *same* TravelBuddy scenario, so learners can compare them side by side:
- **Group chat** — a shared conversation with a manager/turn-taking policy selecting who speaks next. Good for open-ended collaboration/debate among peers.
- **Handoff** (Step 7, existing) — runtime, user-driven routing where the next expert isn't known in advance.
- **Workflow** (Step 8, existing) — a known-ahead pipeline. Note it covers **both sequential** (`SequentialBuilder` / a linear graph) **and parallel/fan-out** (`ConcurrentBuilder` / branching graph that gathers) — one builder, two topologies — so we don't need separate steps for sequential vs. parallel.
- **Magentic** — the Magentic-One-style manager that plans, delegates, and tracks progress against a ledger for complex, open-ended tasks.
For each flavor: a one-paragraph "when to use / when not to," a minimal runnable snippet, the hosting caveat (e.g. the handoff `termination_condition` + silent-routing pairing), and a link to the matching Agent Framework docs/sample. A single decision table ("user drives the path → handoff; process known ahead → workflow; peers collaborate → group chat; open-ended planning → magentic") would tie it together.
Keep it KISS and teaching-quality per the repo conventions: reuse the existing Coordinator/specialist agents so the *only* thing that changes between flavors is the orchestrator, and keep any new solution under `.workshop/solutions/` in sync with its step doc and `.workshop/step_files/`.
## Alternatives considered
- **Do nothing / leave it at handoff + workflow.** Simplest, but leaves `SequentialBuilder`/`ConcurrentBuilder` mentioned-but-never-shown and omits group chat and magentic entirely.
- **A single non-runnable comparison table** in the Step 7 concept section (no code). Lower maintenance, but learners don't get to *feel* the difference.
- **Separate steps for sequential and parallel.** Rejected — the workflow builder already expresses both topologies, so that would duplicate Step 8 rather than teach something new.
- **Full A2A / multi-deployment tour.** Out of scope here; Step 7 already discusses in-process vs. A2A. This request is specifically about the *in-process orchestration* flavors.
Contributor guide
Research direction
Read the existing Step 7 and Step 8 materials, then inspect the related content under .workshop/step_files/ and .workshop/solutions/. Reuse the existing Coordinator and specialist agents while comparing group chat, handoff, workflow, and magentic orchestration. Done means the tour, runnable examples, hosting caveats, decision table, documentation links, and synchronized solution files are complete.
Written by the indexing model from the issue text.
Assessment
- Tech stack
- azure, python
- Domain
- ai, documentation
- Issue type
- Feature
- Difficulty
- 4/5
- Estimated time
- 3-5 days
- Activity status
- Quiet
- Clarity
- Mostly clear
- Newbie friendliness
- 48/100