Sub-agents overview (Customer Conversation) (preview)

[This article is prerelease documentation and is subject to change.]

A sub-agent is a specialist agent that you build directly inside your primary agent to handle a focused intent, such as billing or technical support. Unlike a connected agent, a sub-agent shares its configuration, deployment, and application lifecycle management (ALM) with the primary agent it belongs to.

Sub-agents vs. connected agents

Use a sub-agent when you don't need separate configuration, authentication, deployment, or publishing for a specialist agent. Use a connected agent when the specialist agent needs its own ALM, ownership, or team, or when you want to reuse it across multiple primary agents.

Comparison Sub-agent Connected agent
Configuration and deployment Shared with the primary agent Independent
Ownership Same as the primary agent Can be owned by a different team
Reuse across primary agents No Yes
Source Built directly in the primary agent Currently only Azure AI Foundry agents
Removal Delete the sub-agent Remove (keeps the connection) or delete (permanent)

Sub-agent fields

When you create a sub-agent, configure the following fields:

  • Name: Up to 42 characters.
  • Description: Up to 1,024 characters. The primary agent's orchestration uses the description to decide when to route a conversation to this sub-agent. Write a description that's specific and doesn't overlap with your other sub-agents.
  • Instructions: Up to 20,000 characters. Define the sub-agent's role, tone, and any rules or guidelines it must follow.
  • Skills, tools, and knowledge: Configure the same way you would for a primary agent, scoped to what this sub-agent needs to handle its intent.
  • Input and output variables: Pass data between the primary agent and the sub-agent.

How routing to a sub-agent works

The primary agent's orchestration evaluates each user message against the name, description, and instructions of every sub-agent, along with the primary agent's own instructions. It uses this evaluation to decide whether to handle the request itself or route it to a sub-agent.

Tip

Avoid similar names or descriptions across sub-agents, skills, topics, and tools. Overlapping descriptions make it harder for the orchestrator to route requests correctly. Write explicit routing guidance in the primary agent's instructions when you have sub-agents that could otherwise be ambiguous.

Best practices for working with sub-agents

The Customer Conversation harness works best when sub-agents are independent, almost like different departments in a contact center. Independent sub-agents help route the right context to the right escalation paths, such as different contact center queues.

  • The primary agent's description and instructions shouldn't be mistaken for any of its sub-agents'. Give each agent a distinct role so the orchestrator can tell them apart.
  • Sub-agents should generally be mutually exclusive, each with a clearly defined role. Give a sub-agent its own set of tools and knowledge so it can answer a particular kind of question well on its own.
  • To get sub-agents to act more fluidly together, use / in an agent's instructions to reference other sub-agents by name. For example, in the primary agent's instructions: "If a user wants to pay their credit card using a checking account from the same bank, ask the /CheckingAccountAgent to first confirm the balance, then have the /CreditCardAgent make the payment."
  • The primary agent routes between sub-agents. Think of it as the brains of the routing.

The following table shows what each type of agent can reference:

Referencing Tools Topics Events Sub-agents Variables
Primary agent Yes Yes Yes Yes Yes
Sub-agent Yes Yes Yes No Yes
Connected agent No No No No No

Tip

To best preserve context discussed within a topic when control returns to the generative orchestration, save the topic's output as a variable.

  • Last updated on