Add a child agent

A child agent is a lightweight agent that exists within the context of your main agent. Child agents let you logically group tools, instructions, and knowledge into clearly defined subagents within a larger agent. They're ideal for single use cases that respond to a single intent or complete a single task. This article explains how to create and manage a child agent.

Create a child agent

1. Go to the Agents page for your main agent and select Add an agent.

2. Select New child agent.

3. Enter a distinctive name for your new child agent.

4. Determine when your agent should be used. By default, agents respond to users or triggers, based on their description.

   • If you want to use the default behavior (The agent chooses - Based on description), enter a brief description of your agent's purpose.
   • Otherwise, expand the list under When will this be used? and select the desired behavior. For more information on the supported behaviors, see Determine when to use your agent.

5. Enter clear instructions that you want your agent to follow when invoked. To reference tools, variables, or add Power Fx formulas in your instructions, enter a slash (/) and select the desired option from the menu that appears.

   Important

   When referencing existing tools in your instructions, decide if the tool should be accessible directly by your main agent or only when explicitly called within instructions. Limiting a tool's usage to explicit instruction references helps prevent confusion when similar tools or agents exist. For example, if you have a "Check account balance" agent and a similar "Get account balance" tool, restrict the tool to be called only by the agent to avoid overlap. To restrict a tool to only be available when referenced from another agent, clear the Allow agent to decide dynamically when to use this tool property in the Additional details section on the tool's detail page.

6. Optionally, add knowledge and tools that only this child agent might use:

   • In the Knowledge section, select Add and proceed in the same fashion as when you add knowledge to your main agent.
   • In the Tools section, select Add and proceed in the same fashion as when you add tools to your main agent.

7. If you don't want this agent to be active yet, turn off Enabled. You can make your child agent active later.

8. Select Save.

Manage inputs and outputs

By default, a child agent receives a natural language task to accomplish from the main agent when the agent calls it. Then, when it completes its task, it returns a natural language summary of what happened during its execution. In some cases, you might want to specify more explicit input and output values for the agent.

To manage inputs

1. Go to the child agent details.

2. Scroll down to the Inputs section.

3. To add an input, select Add Input. Define a Display name and Description, which help the agent understand the purpose of the input so that it can fill the input with a relevant value when calling this agent.

4. Select a Data type.

5. Optionally, select Make this input required to require the input has a value before the agent can be called.

6. Select Save.

To manage the list of outputs

1. Go to the child agent details.

2. Scroll down to the Outputs section.

3. To see the current list of outputs, expand the Advanced section within the Outputs section.

4. To add an output, select Add Output. Define a Display name and Description, which help the agent understand the purpose of the output so that it can fill it with a relevant value when returning values to the calling agent.

5. Select a Data type.

6. Select Save.

Within the Outputs section, you can also choose to have a message sent to the user immediately after your child agent finishes. To send the message, change the After running selection.

Determine when to use your agent

By default, child agents respond to a user query based on their description. You can also configure child agents to intercept other events and respond to them under When will this be used?.

Other details

Depending on your selection for When will this be used?, more properties might be available. The following properties are always available.

Condition

Specify conditions that must be met in order for the agent to be called. For example, you might want the agent to be called only if the channel used by an employee is Microsoft Teams.

If you need more complex conditions, you can switch to the Power Fx formula editor: select Builder then select Formula.

Priority

More than one agent can fire for a single incoming activity, such as a message. By default, the option you select for When will this be used? determines the order the agents fire.

Child agents and topics share the same set of triggers or events that they can respond to. If an agent and a topic are configured to respond to the same event, such as user inactivity, use the priority property to determine which one goes first.

Order of execution:

1. An activity occurs
2. A message is received / A custom client event occurs / The conversation changes / It's invoked
3. The agent chooses

If multiple agents or topics must be called based on the same type of event, they're called in the order of creation (oldest first).

You can set the Priority property explicitly. A lower number indicates a higher priority.