Azure-Samples / Azure-Samples/foundry-hosted-agents-workshop

[Feature] Showcase more multi-agent orchestration flavors (group chat, handoff, workflow, magentic)

Open
#18 0 comments 0 reactions 0 assignees View on GitHub
enhancement
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

Open the contributing 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

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.