Skip to content
⚠️ Before You Start
Risk: Medium
Duration: 2-3 days
Last Validated: Not yet validated (draft)
Kind: How-to
Risk Note: Medium (missing termination makes chats run on)

Build group chat, handoff and Magentic orchestrations in Microsoft Agent Framework

Draft outline: not validated

Drafted with AI from official sources on 16 Oct 2026. Do not use on a live system until it is written, dry-run by someone other than the author and signed off (planned 2026-12-09). Author: James · dry-run: Sivaraj · sign-off: Prasanna. Work items: AGT-06-T09, AGT-06-T10, AGT-06-T11, AGT-06-T12.

1. Summary

When the client is Microsoft-first or an existing Semantic Kernel or AutoGen multi-agent solution moves to Agent Framework.

Risk: Medium (missing termination makes chats run on). Typical duration: 2-3 days.

2. When to use and when not to

Use it when: When the client is Microsoft-first or an existing Semantic Kernel or AutoGen multi-agent solution moves to Agent Framework.

Do not use it when: to be written by the author.

3. What you must know first

  • GroupChatBuilder takes participants, a selection function or orchestrator agent, and a termination condition
  • HandoffBuilder restricts which agents can hand off and supports autonomous turn limits
  • MagenticBuilder sets max round, stall and reset counts
  • Workflows checkpoint at superstep boundaries; Cosmos DB storage suits production
  • Tool approval pauses the workflow with a request event

4. Prerequisites and access

  • Foundry project and model deployment
  • agent-framework packages pinned
  • Azure CLI login or managed identity
  • Checkpoint storage chosen

5. Steps

Outline of the steps; the author adds the commands and a check after each one.

  1. Create agents with clear, short instructions
  2. Pick the builder that matches the decision record
  3. Set termination and round limits explicitly
  4. Add checkpoint storage for long-running work
  5. Mark side-effecting tools as approval-required
  6. Run and stream events; log each agent turn
  7. Test termination, approval and restore from checkpoint

Draft snippet: Agent Framework group chat with round-robin and termination

import asyncio
from agent_framework import Agent
from agent_framework.foundry import FoundryChatClient
from agent_framework.orchestrations import GroupChatBuilder
from azure.identity import AzureCliCredential

client = FoundryChatClient(project_endpoint="${FOUNDRY_PROJECT_ENDPOINT}",
                           model="${MODEL_DEPLOYMENT}", credential=AzureCliCredential())
proposer = Agent(client=client, name="Proposer", instructions="Propose a design in five bullets.")
critic = Agent(client=client, name="Critic",
               instructions="List the two biggest flaws. Reply APPROVED if there are none.")

def round_robin(state) -> str:
    names = list(state.participants.keys())
    return names[state.current_round % len(names)]

def stop(conversation) -> bool:  # round cap plus approval phrase
    return len(conversation) >= 6 or (bool(conversation) and "APPROVED" in conversation[-1].text)

workflow = GroupChatBuilder(participants=[proposer, critic], selection_func=round_robin,
                            termination_condition=stop).build()

async def main() -> None:
    async for event in workflow.run("Design a refund approval flow", stream=True):
        print(event)

asyncio.run(main())

Snippets to add:

  • snippets/templates/maf/group_chat.py: Group chat debate workflow (python)
  • snippets/templates/maf/handoff.py: Handoff workflow with approval tool (python)
  • snippets/templates/maf/magentic.py: Magentic workflow with limits (python)

6. Verify it works

A second engineer runs the group chat sample against a sandbox Foundry project and passes when it stops by approval or round cap and every turn appears in traces; API names are re-checked against current docs.

7. Known issues and fixes

Symptom Likely cause Fix
Chat continues past the useful point Termination only on a phrase the agent rarely says Add a round cap alongside the phrase
Restore from checkpoint fails Topology or executor IDs changed Keep IDs stable; rehydrate with the same workflow shape
Plan review never appears in Python enable_plan_review is off by default Set it explicitly when review is needed

8. Monitoring and alerts

Signal Alert when Action
Rounds per workflow run Runs hitting the round cap above 10 percent Review instructions and termination
Pending request events older than the approval timeout Any Run PB-AGT-05-03

9. AWS and open-source equivalents

On AWS, Strands or LangGraph on AgentCore Runtime fill this role. AutoGen-style group chats map to LangGraph custom workflows in open source.

10. Validation record

Pending. Planned dry-run scenario: A second engineer runs the group chat sample against a sandbox Foundry project and passes when it stops by approval or round cap and every turn appears in traces; API names are re-checked against current docs.

11. Sources