Note
Access to this page requires authorization. You can try signing in or changing directories.
Access to this page requires authorization. You can try changing directories.
A voice-based agent holds a live, spoken conversation with a caller. By using subagents, a voice-based agent can divide its work into focused parts while the caller keeps talking to one voice-based agent in one session.
This article describes the problems that subagents solve, introduces inline subagents and delegate subagents, shows which problems each type solves, and walks through an example of each type.
Challenges of one large agent prompt
Most voice-based agents start with one prompt that holds every role, rule, and tool. One prompt works well for a simple conversation. As the business logic grows, the following problems appear:
- Higher cost per turn. Every response reads the whole prompt, including rules for stages that the call never reaches.
- Slower first replies. A longer prompt gives the model more input to process before it starts to speak.
- Wrong tool calls. Every attached tool is a valid choice on every turn. As the tool list grows, the model is more likely to call the wrong tool, call a tool when it shouldn't, or invent tool arguments.
- Unclear conversation stages. Rules for greeting, verification, resolution, and wrap-up are mixed in one prompt. A rule for one stage can change behavior in another, and the prompt can grow past the model's instruction limit.
- Hard to test and debug. Any edit can affect any stage, so each change requires retesting the whole call. When a call fails, it's hard to trace the failure to one rule or one tool.
- No view of where callers drop off. One prompt doesn't report which part of it the conversation is following. When a caller hangs up, gives up, or a call fails, you can't tell at which step it happened, so you don't know which part of the flow to improve.
- Long-running tasks. Some tasks, such as a multistep search or a detailed analysis, take longer than one conversational turn and can need their own model, instructions, and tools. Doing this work in the voice-based agent adds those instructions and tools to the voice prompt, and the voice-based agent has to manage the wait while the caller is on the line.
If your voice-based agent has one or more of these problems, consider subagents.
What is a subagent?
A subagent gives one part of a voice-based agent's work its own instructions and tools. You configure subagents in the subagent_config property of the voice-based agent definition. The subagent_type property selects one of two mutually exclusive types. The two types share this property, but they're different things:
- Inline subagents are stages inside one voice-based agent. Each stage has its own instructions, tools, and optional voice. Inline subagents aren't separate agent resources: they're defined and versioned with the voice-based agent. Moving from one inline subagent to the next is called a handoff. To start a handoff, the model calls a handoff tool that the service generates from the handoff conditions of the active subagent. After a handoff, the target inline subagent becomes active and talks to the caller on subsequent turns.
- Delegate subagents are separate agents. A delegate subagent is a text agent, either a Foundry prompt agent or a hosted agent, in the same Foundry project. The voice-based agent holds the conversation, delegates a bounded task to the text agent, receives the result, and speaks it to the caller. The caller always talks to the voice-based agent, and the delegate text agent never speaks to the caller directly.
Problems each subagent type solves
Inline subagents solve most of the problems of one large prompt. Delegate subagents solve long-running tasks.
| Problem | Solved by | How it helps |
|---|---|---|
| Higher cost per turn | Inline subagent | Within a stage, each turn reads only the shared instructions and the active subagent's instructions, not every rule. |
| Slower first replies | Inline subagent | The first reply of the call reads the entry subagent's shorter prompt instead of every rule. |
| Wrong tool calls | Inline subagent | The model can call only the active subagent's tools. Each subagent has a short, focused tool list. |
| Unclear conversation stages | Inline subagent | Each stage is its own subagent, and handoff conditions state when the conversation moves to the next stage. The total business logic can be larger than one prompt allows. |
| Hard to test and debug | Inline subagent | Each behavior and tool belongs to one subagent, so you fix and retest one subagent and its handoffs instead of the whole call. |
| No view of where callers drop off | Inline subagent | Each stage is a subagent with its own ID. The session reports the active subagent and each handoff, so you can see which stage each call reached and where callers drop off or calls fail. |
| Long-running tasks | Delegate subagent | The text agent does the work with its own model, instructions, and tools. Meanwhile, the voice-based agent stays on the call and can acknowledge the request or speak progress updates until the result arrives. |
| Existing text agent logic to reuse | Delegate subagent | The voice-based agent consults an existing text agent in the project without changing it. |
Inline subagents also have trade-offs. The reply after a handoff processes the new subagent's instructions and the conversation so far as new input, so it costs more and can start later than a reply from one cached prompt. A handoff condition is guidance to the model, not an authorization rule, and the conversation history continues across handoffs. To learn how inline subagents work, how they affect cost and latency, and when one prompt is enough, see Use an inline subagent in a voice-based agent.
Compare inline and delegate subagents
Use the following table to compare the two subagent types and choose the one that fits your scenario.
| Aspect | Inline subagent | Delegate subagent |
|---|---|---|
| How it works | One voice-based agent runs a flow of stages. A handoff switches which inline subagent is active. | The voice-based agent delegates a task to a separate text agent and speaks the returned result. |
| What it is | A set of instructions, tools, and voice settings defined and versioned inside the voice-based agent. | A Foundry prompt agent or hosted agent in the same project, versioned as its own agent resource. |
| Who talks to the caller | The active inline subagent. It owns subsequent turns until the next handoff. | The voice-based agent, for the whole call. It can acknowledge the request, fill silence, or speak progress updates while it waits. |
| How it's selected | The model calls the handoff tool for one of the active subagent's handoff conditions. | The voice-based agent forwards a request that matches the text agent's agent_capabilities, a description of what the text agent does. |
| Model | All inline subagents use the voice-based agent's real-time model. With a cascaded pipeline, where speech recognition, the language model, and text to speech run as separate steps, a subagent can select its own compatible model. | The delegate text agent has its own model. Both the voice-based agent and the delegate text agent can use any supported model. |
| Instructions and tools | The shared top-level instructions, plus the active subagent's own instructions and tools. | The text agent's own instructions and tools. |
| Conversation history | The full conversation history continues across handoffs. | The delegate text agent receives only the request that the voice-based agent sends. |
| Best for | Moving a call through stages, keeping each stage's prompt and tool list short, letting one subagent own several turns, or changing the voice when a role takes over. | A bounded task that takes longer than one conversational turn, or reuse of an existing text agent in the project. |
One voice-based agent version uses either inline or delegate subagents. You can't mix the two types in one subagent_config. If you omit subagent_type, the voice-based agent uses delegate subagents.
Examples
The following examples show how inline subagents and delegate subagents work in a conversation.
Example: split a conversation into inline subagent stages
A customer-care agent handles billing questions and device problems. You can split its one large prompt into five inline subagents connected by handoffs:
- A triage subagent greets the caller and identifies the request. Because it's the first subagent of the conversation, it's the entry subagent. It hands off to an authentication subagent.
- The authentication subagent verifies the caller. It then hands off to a billing subagent for a billing question, or to a support subagent for a device problem.
- The billing subagent resolves the question by using billing tools that are assigned only to it. The support subagent troubleshoots the device by using its own support tools.
- Both the billing and support subagents hand off to a confirmation subagent, which summarizes the outcome and ends the conversation.
At each stage, the model reads the shared instructions plus the active subagent's instructions, and it can call only the active subagent's tools. A billing call never reads the support rules. The caller stays in the same session, and the conversation history carries over across each handoff. To configure this pattern, see Use an inline subagent in a voice-based agent.
Example: delegate a long task to a delegate subagent
A voice-based travel assistant helps a caller plan a trip. The caller asks it to find hotels that match a list of location, price, and amenity requirements. The search takes multiple steps and doesn't fit into one conversational turn:
- The voice-based agent delegates the search to a separate research text agent, which is the delegate subagent.
- While the research text agent works, the voice-based agent stays on the call and tells the caller that it's looking into the request.
- The research text agent finishes and returns a short list of hotels.
- The voice-based agent presents the options and continues the spoken conversation with the caller.
The caller talks only to the voice-based agent, and the research text agent never speaks to the caller. Unlike a handoff, delegation doesn't change which instructions the voice-based agent follows: the search instructions and tools stay in the research text agent. To configure this pattern, see Use a delegate subagent in a voice-based agent.