Semantic Kernel Advanced Multi‑Agent (Python)
Advanced multi-agent patterns in Semantic Kernel (Python) — custom group-chat managers, hand-offs with human input, routing, structured results and resilience.
Verified against
semantic-kernel1.45.0 (checked 2026-11-19). Orchestrations are experimental in Semantic Kernel; Microsoft Agent Framework’s workflows are their supported successor — see the comprehensive guide.
import asynciofrom typing import Annotatedfrom semantic_kernel.agents import ( ChatCompletionAgent, GroupChatOrchestration, RoundRobinGroupChatManager, HandoffOrchestration, OrchestrationHandoffs,)from semantic_kernel.agents.runtime import InProcessRuntimefrom semantic_kernel.connectors.ai.open_ai import OpenAIChatCompletionfrom semantic_kernel.contents import AuthorRole, ChatMessageContentfrom semantic_kernel.functions import kernel_function
service = OpenAIChatCompletion(ai_model_id="gpt-6-luna") # reads OPENAI_API_KEY
class SearchPlugin: @kernel_function(description="Search the web and return result snippets.") async def web_search(self, query: Annotated[str, "Search query"]) -> str: return f"(results for {query})" # wrap your provider; add timeouts and retries
def make_agent(name: str, description: str, instructions: str, plugins=None) -> ChatCompletionAgent: return ChatCompletionAgent( name=name, description=description, instructions=instructions, service=service, plugins=plugins or [], )
researcher = make_agent("Researcher", "Finds facts with sources", "Research the topic. Cite sources. Be concise.", [SearchPlugin()])writer = make_agent("Writer", "Drafts copy", "Write clear, short copy from the research.")reviewer = make_agent("Reviewer", "Checks drafts", "Review the draft. Reply 'APPROVED' if it is good, otherwise list fixes.")1. Group chat with a custom manager
Section titled “1. Group chat with a custom manager”RoundRobinGroupChatManager just takes turns. Subclass it (or the abstract GroupChatManager) to change who speaks next and when to stop. Here the subclass keeps round-robin turn-taking and max_rounds, and also stops as soon as the reviewer approves.
from semantic_kernel.agents import BooleanResultfrom semantic_kernel.contents import ChatHistory
class ReviewLoopManager(RoundRobinGroupChatManager): async def should_terminate(self, chat_history: ChatHistory) -> BooleanResult: base = await super().should_terminate(chat_history) # honours max_rounds if base.result: return base last = chat_history.messages[-1] if chat_history.messages else None approved = bool(last and last.name == "Reviewer" and "APPROVED" in str(last.content)) return BooleanResult(result=approved, reason="Reviewer approved" if approved else "Keep going")
async def run_review_loop(task: str) -> str: orchestration = GroupChatOrchestration( members=[researcher, writer, reviewer], manager=ReviewLoopManager(max_rounds=9), agent_response_callback=lambda m: print(f"[{m.name}] {str(m.content)[:80]}"), ) runtime = InProcessRuntime() runtime.start() try: result = await orchestration.invoke(task=task, runtime=runtime) return str((await result.get(timeout=300)).content) finally: await runtime.stop_when_idle()The manager can also override select_next_agent (return a StringResult naming the agent) and filter_results (decide what the orchestration returns). An LLM-driven manager is a manager whose methods call a chat service.
2. Hand-off with a human in the loop
Section titled “2. Hand-off with a human in the loop”triage = make_agent("Triage", "Routes requests", "Work out what the customer needs and hand off.")billing = make_agent("Billing", "Invoices and refunds", "Handle billing questions. Never promise refunds.")tech = make_agent("Tech", "Technical support", "Troubleshoot technical issues step by step.")
handoffs = ( OrchestrationHandoffs() .add_many(source_agent=triage.name, target_agents={ billing.name: "Billing, invoices, refunds", tech.name: "Errors, outages, how-to questions", }) .add(source_agent=billing, target_agent=triage, description="Not a billing issue") .add(source_agent=tech, target_agent=triage, description="Not a technical issue"))
def ask_human() -> ChatMessageContent: return ChatMessageContent(role=AuthorRole.USER, content=input("customer> "))
support = HandoffOrchestration( members=[triage, billing, tech], handoffs=handoffs, human_response_function=ask_human, # called when an agent needs more input)add() needs agent objects (not names) for target_agent if you want its description kept; with a string target the description is dropped in 1.45.0. add_many() with a name-to-description dict is fine.
In a web service, human_response_function can await a queue that your HTTP handler fills, instead of input().
3. Deterministic routing in front of the LLM
Section titled “3. Deterministic routing in front of the LLM”Keyword or classifier routing is cheaper and testable. Use it to pick the orchestration (or a single agent), and fall back to the LLM triage agent when unsure:
def route(message: str) -> ChatCompletionAgent | None: text = message.lower() if any(w in text for w in ("invoice", "refund", "charge")): return billing if any(w in text for w in ("error", "crash", "timeout")): return tech return None # ambiguous: let the hand-off orchestration decide
async def answer(message: str) -> str: agent = route(message) if agent: return str((await agent.get_response(messages=message)).message.content) runtime = InProcessRuntime(); runtime.start() try: result = await support.invoke(task=message, runtime=runtime) return str(await result.get(timeout=300)) finally: await runtime.stop_when_idle()4. Typed results with output_transform
Section titled “4. Typed results with output_transform”from pydantic import BaseModelfrom semantic_kernel.agents import ConcurrentOrchestration
class Opinions(BaseModel): optimist: str sceptic: str
optimist = make_agent("Optimist", "Sees upsides", "Give the strongest case for.")sceptic = make_agent("Sceptic", "Sees risks", "Give the strongest case against.")
def to_opinions(messages: list[ChatMessageContent]) -> Opinions: by_name = {m.name: str(m.content) for m in messages} return Opinions(optimist=by_name["Optimist"], sceptic=by_name["Sceptic"])
debate = ConcurrentOrchestration[str, Opinions](members=[optimist, sceptic], output_transform=to_opinions)5. Resilience
Section titled “5. Resilience”- Timeouts. Always pass
timeout=toresult.get(); an orchestration waiting on a model that never answers otherwise waits forever.result.cancel()stops it. - Retries. Put retries in plugins (e.g.
tenacity) for flaky tools; theopenaiclient under the OpenAI connectors already retries 429 and 5xx responses (two retries by default). - Loop limits. Set
max_roundson group-chat managers; for hand-offs, keep hand-off descriptions specific so agents do not bounce requests between each other. - Idempotent tools. A retried or repeated tool call must not double-charge or double-send.
6. Observability and testing
Section titled “6. Observability and testing”agent_response_callbackgives every agent message — log agent name, length and latency with a request ID.- Semantic Kernel emits OpenTelemetry spans for agent invocations and function calls; see the middleware page for filters that add your own attributes.
- Test routers and managers as plain Python (they are deterministic); test agents against a stub chat service (subclass
ChatCompletionClientBaseand return canned messages).
Revision history
Section titled “Revision history”| Date | Version | Changes |
|---|---|---|
| 2026-10-25 | 1.45.0 | Hand-off add() example passes agent objects so descriptions are kept; retry claim corrected. |
| 2026-10-21 | 1.45.0 | Rewritten on the orchestration API and run against a stub chat service. |