Connected Agent Architecture
Connected agents are a first-class multi-agent pattern in Azure AI Foundry Agent Service. They allow one agent — the Orchestrator AgentThe top-level agent that holds the conversation thread, routes user queries to specialist agents, and synthesizes responses. It does not directly handle domain-specific tasks. — to delegate subtasks to one or more Specialist AgentA narrowly scoped agent registered as a connected agent tool on the orchestrator. It has its own system prompt, model, tools, and thread — separate from the orchestrator. agents by registering each specialist as a tool on the orchestrator. The orchestrator decides at runtime which specialist to invoke based on the user's request; the specialist runs its own model call (with its own system prompt, tools, and context), and returns a result the orchestrator incorporates into its final reply.
User → Orchestrator Agent
├── Connected Agent: "billing-specialist"
├── Connected Agent: "hr-specialist"
└── Connected Agent: "tech-support-specialist"
The orchestrator holds the conversation thread and system prompt that govern routing decisions. Each specialist has its own system prompt scoped to its domain. Neither specialist knows about the others — only the orchestrator has visibility across all specialists.
Key Components
| Component | Role |
|---|---|
| Orchestrator agent | Receives user turns, decides which specialist to call, merges the response |
| Specialist (connected) agent | Handles a narrowly scoped task; has its own model, tools, and instructions |
| ConnectedAgentToolThe SDK class (azure.ai.projects.models.ConnectedAgentTool) used to bind a specialist agent to an orchestrator by Agent ID, tool name, and tool description. | The registration object the orchestrator uses to invoke a specialist |
| Agent ID | The unique identifier of the specialist agent; bound at configuration time |
| Tool name | A snake_case label the orchestrator's LLM uses to pick the right specialist |
| Tool Description (Connected Agent)The natural-language text injected into the orchestrator's context that the LLM reads to decide when to delegate to the specialist. This is the most critical field — vague descriptions are the leading cause of routing failures. | Natural-language text that tells the orchestrator when to call this specialist |
Adding a Connected Agent as a Tool
In the Azure AI Foundry portal you add a specialist to an orchestrator on the orchestrator's Tools tab:
- Select + Add tool → Agent.
- Choose the specialist agent from the dropdown (this populates the Agent ID).
- Enter a short Tool name (e.g.,
billing_agent). - Enter a Tool description — this is critical: it is injected into the orchestrator's context and used by the LLM to decide when to route to this specialist.
Programmatically (Python SDK):
from azure.ai.projects.models import ConnectedAgentTool
billing_tool = ConnectedAgentTool(
id=billing_agent.id, # specialist agent ID
name="billing_agent", # tool name used by the orchestrator LLM
description=(
"Handles questions about invoices, subscriptions, "
"payment history, and billing disputes."
),
)
orchestrator = project_client.agents.update_agent(
agent_id=orchestrator.id,
tools=billing_tool.definitions,
)
Writing Effective Tool Descriptions
The description is the primary signal the orchestrator's LLM uses to route. A weak description causes missed delegation or incorrect routing.
| Weak description | Strong description |
|---|---|
| "Billing agent" | "Handles questions about invoices, payment methods, subscription renewals, refunds, and billing disputes. Do NOT use for general product questions." |
| "HR bot" | "Answers questions about employee benefits, leave policies, onboarding checklists, and HR forms. Scope limited to company HR processes." |
Guidelines:
- State explicitly what the specialist handles.
- Add a Do NOT use for clause to prevent false positives.
- Keep it under ~60 words so it fits cleanly in the orchestrator's context window.
Connected Agents vs. Traditional Function Tools
| Dimension | Traditional function tool | Connected agent tool |
|---|---|---|
| Execution | Deterministic code you write | Another LLM-powered agent |
| Context | No conversation thread | Maintains its own thread |
| Flexibility | Fixed logic | Can use sub-tools, RAG, code execution |
| Debugging | Single call log | Nested agent call logs |
| When to use | Structured data retrieval, APIs | Complex reasoning, multi-step subtasks |
Use Cases for Connected Agents
- Routing by domain — A customer service orchestrator routes billing questions to a billing specialist and technical questions to a support specialist.
- Specialisation — Each specialist is trained (system prompt + tools) for a narrow domain, producing higher accuracy than a single generalist agent.
- Parallel task execution — The orchestrator can invoke multiple specialists in a single turn when the user's request spans domains; results are merged before responding.
- Layered architectures — A specialist can itself be an orchestrator with its own connected agents, enabling deep agent hierarchies.
Hands-On: Register a Specialist as a Connected Agent
Goal: Register a specialist agent as a connected agent on an orchestrator in the Foundry portal.
- Open Azure AI Foundry at
https://ai.azure.comand navigate to your project. - Create the specialist agent — in the left nav select Agents → + New agent. Give it a focused system prompt (e.g., "You are a billing expert. Answer only questions about invoices and payments."). Save and note its Agent ID.
- Open the orchestrator agent — select your orchestrator agent from the Agents list.
- Add the connected agent tool — on the orchestrator's detail page, select the Tools tab → + Add tool → Agent.
- Configure the tool — in the dialog, select the specialist from the dropdown, enter a
tool_name(snake_case), and write a precisetool_description. Click Save. - Verify the tool appears — the Tools tab should now list the specialist under "Connected agents". Confirm the Agent ID matches the specialist you created.
- Review the orchestrator system prompt — optionally add a routing instruction such as: "When the user asks about billing, delegate to billing_agent." This reinforces the description-based routing.
AI-3018 Assessment Focus
Connected agent topology, the role of tool descriptions in routing, and cross-project constraints are the key exam targets for domain 3.
Exam Trap
"The orchestrator and specialist share a conversation thread" — Each agent maintains its own thread. The orchestrator passes the relevant context when invoking a specialist; the specialist's thread is separate.
Exam Trap
"The tool name is used by the portal UI only" — The tool name is surfaced to the orchestrator's LLM at inference time. The LLM uses it (along with the description) to decide which tool to call — choose names that are self-explanatory.
Exam Trap
"Any agent can be added as a connected agent to any orchestrator" — Both agents must exist in the same Azure AI Foundry project (same project endpoint). Cross-project connected agents are not supported.
Exam Trap
"Connected agents run in parallel automatically" — Parallel invocation is possible but is not the default. The orchestrator model decides whether to call specialists sequentially or in parallel based on its reasoning.
Exam Trap
"The tool description is optional boilerplate" — The description is the most important field. Without a precise description the orchestrator's LLM cannot reliably decide when to delegate.
Must Memorize
The SDK class for registering a specialist on an orchestrator is ConnectedAgentTool from azure.ai.projects.models. It takes id (specialist Agent ID), name (tool name), and description.
Question — click to flip
Q: Which field on a connected agent tool most directly controls when the orchestrator delegates to the specialist?
Question — click to flip
Q: Must connected agents be in the same Foundry project as the orchestrator?
Question — click to flip
Q: What SDK class registers a specialist agent on an orchestrator?
Question — click to flip
Q: Do the orchestrator and specialist share a conversation thread?
Question — click to flip
Q: What is the leading cause of routing failures in connected agent topologies?
Question — click to flip
Q: How does a connected agent tool differ from a traditional function tool?