Connected Agents & the Microsoft Agent Framework

Before you start: this is a billed Azure service

• Cost and account. An Azure subscription, a Foundry project, and model deployments. A multi-agent run makes model calls for each agent involved — cost scales with the number of hops. Tear down test agents.
• Authored against the docs, not executed live. Code is written against the official docs and syntax-checked, not run during authoring. Pin your SDK version and verify.
• Two languages. Python-primary with .NET noted — the Microsoft Agent Framework is first-class in .NET.

About this series

This is Part 9 of the twelve-part Microsoft Foundry series. So far you've built a single, capable agent. Real workflows usually need several agents — a coordinator and specialists. This lab composes them with connected agents and the Microsoft Agent Framework, without standing up an external orchestrator.

What you'll build

You'll turn the Acme assistant into a small multi-agent system:

1. A specialist agent — a returns expert that only handles returns and refunds.
2. A primary agent — the Acme concierge — that delegates returns to the specialist using a connected agent.
3. The orchestration that routes each request to the right agent automatically.

By the end, one request can flow from the concierge to a specialist and back — a coordinated system, not a monolith.

Why this matters (the 5-minute business case)

Read this before handing the lab to your team.

One giant agent that does everything is hard to build, test, and trust. A team of focused agents is easier on every axis. Splitting work into specialists — each with its own instructions, tools, and guardrails — mirrors how human teams actually scale, and it's where multi-agent systems get genuinely powerful.

Three reasons this is a leadership-level concern:

1. Specialization improves quality and maintainability. A returns specialist with a tight scope and the right tools beats a sprawling do-everything prompt. Each agent is smaller, testable, and ownable — and you can improve one without destabilizing the rest.
2. Connected agents lower the orchestration tax. Foundry lets a primary agent call others as tools — no separate orchestration service to build and run. That's the difference between "we designed a multi-agent architecture" and "we shipped one."
3. It composes with the open ecosystem. A specialist can be another Foundry agent today and an external A2A peer tomorrow (Lab 12). Designing in delegation now means the system can reach beyond your walls later without a rewrite.

The honest caveats:

• More agents, more cost and latency. Each hop is model calls. Delegate where specialization earns it; don't fan out for its own sake.
• Orchestration is a new failure surface. A delegated call can loop, stall, or mis-route. Keep instructions crisp about when to delegate, and watch it with tracing (Lab 10).
• Governance still applies per agent. Each specialist needs its own least-privilege tools (Lab 4), safety (Lab 7), and identity (Lab 8). A team of agents is a bigger surface, not a smaller one.

A framing for a non-technical stakeholder: "Instead of one agent that tries to do everything, we build a small team — a coordinator that hands specialized work to expert agents. Each is focused, testable, and owns its part, and the platform handles the hand-offs."

Concepts you'll use (2-minute primer)

• Primary (coordinator) agent — the agent the user talks to; it decides what to handle itself and what to delegate.
• Connected agent — another agent exposed to the primary as a tool, so the primary can call it mid-conversation. No external orchestrator required.
• Specialist agent — a focused agent (e.g., returns) with its own instructions, tools, and guardrails.
• Microsoft Agent Framework — the framework for building and orchestrating agents (the successor lineage to Semantic Kernel / AutoGen); first-class in .NET and available in Python.

One sentence: build focused specialist agents, expose them to a coordinator as connected agents, and the platform routes each request to the right one.

Prerequisites

Step 1 — Build a specialist agent

A focused returns expert — tight scope, its own instruction:

import os
from azure.ai.projects import AIProjectClient
from azure.identity import DefaultAzureCredential

project = AIProjectClient(
    endpoint=os.environ["FOUNDRY_PROJECT_ENDPOINT"],
    credential=DefaultAzureCredential(),
)

returns_specialist = project.agents.create_version(
    agent_name="acme-returns-specialist",
    definition={
        "model": "gpt-5-mini",
        "instructions": (
            "You are Acme's returns specialist. Handle only returns and refunds: "
            "eligibility, windows, restocking fees, and starting a return. Be "
            "precise about policy. If asked about anything else, say it's outside "
            "your scope."
        ),
    },
)

Step 2 — Connect it to a primary agent

Expose the specialist to the concierge as a connected agent, so the concierge can delegate to it:

from azure.ai.agents.models import ConnectedAgentTool

returns_tool = ConnectedAgentTool(
    id=returns_specialist.id,           # or name, per your SDK version
    name="returns_specialist",
    description="Handles Acme returns and refunds. Delegate return questions here.",
)

concierge = project.agents.create_version(
    agent_name="acme-concierge",
    definition={
        "model": "gpt-5-mini",
        "instructions": (
            "You are the Acme Concierge. Handle order status and general questions "
            "yourself. For anything about returns or refunds, delegate to the "
            "returns_specialist. Be concise and never guess."
        ),
        "tools": returns_tool.definitions,
    },
)

The concierge now treats the specialist like a tool it can call — the platform handles the hand-off. No orchestration service in between.

The exact ConnectedAgentTool constructor (id vs name) and wiring vary by SDK version. Pin your version and check the docs; the pattern — a specialist exposed to a coordinator as a connected agent — is stable.

.NET note: the Microsoft Agent Framework is first-class in C# for exactly this — building agents and orchestrating multi-agent workflows (sequential, concurrent, hand-off). The connected-agent concept maps directly.

Step 3 — Run it and watch the hand-off

Send the concierge a returns question and watch it delegate:

thread = project.agents.threads.create()
project.agents.messages.create(
    thread_id=thread.id, role="user",
    content="I want to return opened headphones I bought 10 days ago.",
)
project.agents.runs.create_and_process(
    thread_id=thread.id, agent_name="acme-concierge"
)
for msg in project.agents.messages.list(thread_id=thread.id):
    print(msg.role, msg.content)

Ask about order status and the concierge answers directly; ask about a return and it routes to the specialist. That routing — the right agent for the right request — is the whole point. In Lab 10 you'll see each hop in the trace.

Cost & cleanup

• A multi-agent run is model calls per agent — delete test agents when done (project.agents.delete_version(...) for both).
• Confirm in Cost Management that nothing is still accruing.

If a lab created it and you're done, delete it today.

Verified against

• Microsoft Foundry connected agents (ConnectedAgentTool), the Microsoft Agent Framework, and the `azure-ai-projects` SDK, June 2026.
• The connected-agent constructor and orchestration APIs vary by SDK version; code is syntax-checked against the docs but not executed during authoring. Pin your version.

What's next

You have a multi-agent system. Now make it observable and affordable:

• Lab 10 — Observability & cost: trace every model call, tool, and sub-agent hop, build dashboards and alerts, and control spend.
• Multi-agent systems are exactly where observability stops being optional — you need to see the hand-offs to debug them.