Route specialist work through a controlled hub

Learning objective

Implement hub-and-spoke orchestration with a supervisor routing work to specialized spokes and enforcing communication boundaries

Core idea

A hub-and-spoke design gives one supervisor responsibility for routing work to specialists and assembling the result. A spoke performs its assigned task and returns to the hub. The supervisor decides whether another specialist is needed; the spokes do not create an unrestricted collaboration network.

There are three separate controls: which participant can receive work, which information it receives, and which operations it can execute. A star-shaped diagram establishes none of those controls by itself. Implement each through the routing graph, message contract, and specialist tool configuration.

Microsoft Agent Framework supports agent-as-tool composition, custom workflow edges, and group-chat orchestration with a central manager. Select among them according to whether you need private specialist calls or a shared team conversation. Shared speaker control does not imply private specialist context.

How it works

Choose the hub’s execution mechanism

Expose each specialist through .as_tool() in Python or .AsAIFunction() in .NET; see 1.1.3 for the tool’s parameters and ownership contract.

For the hub’s communication policy, define the request projection and accepted return separately for each spoke. A payroll request might include an employee identifier and authorized pay period, while a travel request receives an itinerary without payroll evidence. These are application-defined message contracts enforced by the dispatch executor, not labels that the supervisor asks every specialist to respect.

Check the return before forwarding it to another spoke. A permitted payroll finding can still contain source records that the travel role must not receive. The hub collector should reject or project that payload into the permitted summary, retaining task and producer identity so later routing remains attributable.

When routing must be deterministic, use WorkflowBuilder edges instead of leaving the choice solely to a model. Conditional add_edge(..., condition=...) connections inspect message properties. Switch-case routing selects a destination through cases and a Default branch; multi-selection edges route to multiple selected destinations when several specialists are required.

Keep specialist return paths explicit

For a custom hub graph, connect hub dispatch to each allowed spoke and each spoke’s result to a hub collector. Do not add spoke-to-spoke edges unless the application actually permits those interactions. Use ctx.send_message(...) to send the result through the defined workflow connections.

A specialist that needs work outside its role returns an application-defined status such as needs_other_specialist with its evidence and reason. The hub decides the next destination. That status is a result, not authorization for the specialist to call an arbitrary peer or invent another participant.

The collector validates the returned task identifier and producer before merging a result into the active request. Preserve an explicit relationship between dispatch and return so two simultaneous tasks do not exchange specialist results. Routing accuracy includes returning to the correct task, not only selecting the correct role. Every return passes through the hub, and the hub decides the next destination.

Recognize what group chat shares

GroupChatBuilder is another central coordination mechanism. Its orchestrator selects the next speaker through selection_func, orchestrator_agent, or a custom orchestrator. A selection function receives GroupChatState; documented state includes participants, current_round, and conversation.

Group chat uses an internal star topology, but the participants collaborate through synchronized conversation history. They do not share one AgentSession object; the orchestrator synchronizes history before each turn and broadcasts responses after turns. Choose it when shared specialist discussion is intended, not merely because its diagram resembles hub-and-spoke routing.

Python group-chat history preserves semantic user content and retains text from non-user messages while filtering tool-control content. This does not remove confidential information that a specialist wrote into ordinary text. A tool result summarized into a response can still enter shared history.

The documented redaction extension point is a custom GroupChatOrchestrator participant-response handler. Filter there before text enters shared history or reaches peers. Filtering events returned by workflow.run() is too late because the original response has already been stored and broadcast.

That filter has a defined scope: it protects shared history and broadcast. It does not erase the source agent’s session, tools, provider processing, telemetry, or earlier lifecycle events. Treat those as separate data handling responsibilities rather than attributing complete isolation to a single filter.

Separate routing from context and authority

HandoffBuilder.add_handoff() restricts control transfers, but the handoff documentation says participants remain connected for context sharing even with custom rules. A hub-only handoff map can therefore restrict the next active speaker without satisfying a requirement that spokes never receive each other’s text.

For private specialist work, prefer agent-as-tool calls or a custom executor graph that constructs each specialist’s input explicitly. Supply only the request fields and evidence required for that role. Make the result contract carry relevant findings without reproducing private source material unnecessarily. See 2.1.5 for context selection details.

Configure each inner agent’s tools for its job. The Microsoft agent-as-tool example gives the inner weather agent its own weather function and exposes the agent to the outer one as a tool. That composition establishes capability exposure; it does not create a downstream permission grant. See 1.1.7 and 1.2.3 for principal and access enforcement.

Do not encode tool authorization only as a supervisor instruction. If a specialist must not perform a payment, omit that capability from its configured tools and enforce access in the integration. A role label such as “read-only reviewer” is insufficient when the runtime still exposes a write operation.

Key distinctions and trade-offs

Agent as tool versus handoff: The specialist returns a subtask result to the supervisor in agent-as-tool composition. A handoff transfers control to another participant; see 2.4.4.

Central routing versus shared conversation: A group-chat manager controls turns, but participants receive synchronized history. Private calls require a different information-flow design.

Communication policy versus access permission: Graph edges determine message paths. Tool configuration determines exposed capabilities. Downstream authorization determines whether the acting principal can perform the operation.

A central hub simplifies accountability and policy enforcement, but concentrates routing work and can become a bottleneck. Shared discussion can improve iterative review, while increasing the amount of information distributed across participants. Choose the communication model before choosing the orchestration builder.

Architecture / decision scenario

An enterprise assistant routes requests to payroll, travel, and procurement specialists. Payroll evidence must remain outside the travel specialist’s context. The supervisor retains responsibility for the user response and can request more than one specialist when a task spans domains.

The team exposes the specialists with .as_tool() and descriptive contracts. The supervisor sends a role-specific query and receives a result for its active task. Payroll returns a permitted summary rather than its source records. Each specialist has only the tools needed for its work, and downstream access remains scoped to the relevant principal.

For deterministic request categories, a custom workflow uses switch-case routing with an explicit unmatched destination. Multi-selection routing handles tasks requiring both travel and procurement; each return passes through the hub collector. A specialist’s request for another role returns to the hub rather than opening a peer call.

The team rejects a group-chat implementation for the payroll path because synchronized history conflicts with the privacy requirement. For a separate public-policy review, it deliberately uses group chat and applies a participant-response filter before shared history. The distinction is enforced in the runtime, rather than implied by the diagram or a prompt.

Common exam traps

• Assuming a star topology prevents shared conversation history.
• Treating handoff rules as a confidentiality filter.
• Redacting only the events displayed to the caller after broadcast.
• Granting every spoke all tools and relying on its role prompt.
• Confusing a specialist tool call with a transfer of user interaction.
• Letting a spoke bypass the hub when it needs another specialty.

What to remember

Choose .as_tool() for supervisor-owned call-and-return work and explicit graph edges for enforced routing. Group chat centralizes speaker selection while sharing history. Enforce routing, information flow, and tool authority separately; a hub diagram is not a complete communication policy.

Knowledge check

References

• Microsoft, Tools overview
• Microsoft, Edges
• Microsoft, Group chat orchestration
• Microsoft, Handoff orchestration
• Microsoft, Executors