# Use multi-agent collaboration with Amazon Bedrock Agents
<a name="agents-multi-agent-collaboration"></a>

Multi-agent collaboration enables multiple Amazon Bedrock Agents to collaboratively plan and solve complex tasks. With multi-agent collaboration, you can quickly assemble a team of agents that can break down tasks, assign specific tasks to domain specialist sub-agents, work in parallel, and leverage each other's strengths, which leads to more efficient problem-solving. Multi-agent provides a centralized mechanism for planning, orchestration , and user interaction for your generative AI applications. 

With multi-agent approach, you can quickly designate an Amazon Bedrock Agent as the supervisor and then associate one or more collaborator agents with the supervisor. You can use this hierarchical collaboration model to synchronously respond to prompts and queries from users in real-time. As your hierarchical model matures, you can add additional collaborator agents to augment its capabilities. 

**Important**  
Before you can enable multi-agent collaboration, you must first save the surpervisor agent. After the supervisor agent has been saved, you can update the agent and associate additional collaborator agents to it.

The supervisor agent uses the instructions you provide to understand the structure and role of each collaborator agent. To ensure that the team performs well, you must clearly designate the role and responsibilities of the supervisor agent and every collaborator agent on the team and minimize overlapping responsibilities. You can describe each agent’s role and responsibilities using natural language. For example, you could use multi-agent collaboration to create an online mortgage assistant. Each Amazon Bedrock agent can be configured to carry out one of the following tasks:
+ **Supervisor agent** – Takes questions from the user, checks if the question is about the existing mortgage, new mortgage, or it is a general question and routes the question to the appropriate collaborator agent.
+ **Collaborator agent 1** – Responsible for handling existing mortgages
+ **Collaborator agent 2** – Responsible for handling new mortgage applications and for answering questions related to new mortgages.
+ **Collaborator agent 3** – Responsible for handling general questions. 

 Each agent on the team, including the supervisor agent, is optimized for a specific use case, has all the capabilities of Amazon Bedrock Agents, including access to tools, action groups, knowledge bases, and guardrails. When you invoke the supervisor agent, it automatically creates and executes a plan across a set of collaborator agents and routes relevant requests and tasks to the appropriate collaborator agent. 

# Supported Regions, models, and Amazon Bedrock Agents features for multi-agent collaboration
<a name="multi-agents-supported"></a>

**Supported models**

You can use the following foundation models for creating a collaborator agent for multi-agent collaboration:
+ Anthropic Claude 3 Haiku
+ Anthropic Claude 3 Opus
+ Anthropic Claude 3 Sonnet
+ Anthropic Claude 3.5 Haiku
+ Anthropic Claude 3.5 Sonnet
+ Anthropic Claude 3.5 Sonnet V2
+  Amazon Nova Pro
+ Amazon Nova Lite
+ Amazon Nova Micro

**Supported Regions**

Multi-agent collaboration is supported in all the Regions where Amazon Bedrock Agents is supported. For more information, see [Model support by AWS Region in Amazon Bedrock](https://docs.aws.amazon.com//bedrock/latest/userguide/models-regions.html).

**Supported Amazon Bedrock Agents features**

You can create and use any Amazon Bedrock Agents with multi-agent collaboration except the following:
+ Supervisor agents and collaborator agents customized with [custom orchestration](https://docs.aws.amazon.com//bedrock/latest/userguide/agents-custom-orchestration.html).

# Create multi-agent collaboration
<a name="create-multi-agent-collaboration"></a>

Creating a multi-agent collaboration comprises of the following steps:

1. Create and deploy collaborator agents. Make sure to configure each collaborator agent to implement a specific task within the multi-agent collaboration work flow. 

1. Create a new supervisor agent or assign an existing agent the role of the supervisor. When you create a new supervisor agent or identify an existing agent as a supervisor agent, you can also specify how you want the supervisor agent to handle information across multiple collaborator agents.

   You can assign the supervisor agent the task of coordinating responses from the collaborator agents or you can assign the supervisor agent the task of routing information to the appropriate collaborator agent to send the final response. Assigning the supervisor agent the task of routing information reduces the latency. 

1. Associate the alias version of the collaborator agents with the supervisor agent.
**Note**  
You can associate a maximum of 10 collaborator agents with a supervisor agent at this time.

1. Prepare and test your multi-agent collaboration team.

1. Deploy and invoke supervisor agent.

You can create multi-agent collaboration in the Amazon Bedrock console, using the APIs, using the AWS CLI, or by using the AWS SDK. To learn how to create a multi-agent collaboration, choose the tab for your preferred method, and then follow the steps:.

------
#### [ Console ]

**Step 1: Create collaborator agents**
+ Follow instructions to [Create and configure an agent](https://docs.aws.amazon.com//bedrock/latest/userguide/agents-create.html). Make sure to configure each collaborator agent to perform a specific task.

**Step 2: Create a new supervisor agent or assign supervisor role to an existing agent**

1. If you are creating a new supervisor agent follow instructions to [Create and configure agent manually](agents-create.md) and then continue with the next step.

   If you already have an agent configured and want to assign supervisor role to the agent, continue with the next step.

1. If you're not already in the agent builder, do the following:

   1. Sign in to the AWS Management Console with an IAM identity that has permissions to use the Amazon Bedrock console. Then, open the Amazon Bedrock console at [https://console.aws.amazon.com/bedrock](https://console.aws.amazon.com/bedrock).

   1. Select **Agents** from the left navigation pane. Then, choose an agent in the **Agents** section.

   1. Choose **Edit in Agent builder**.

   1. In the **Agent builder**, scroll down to the **Multi-agent collaboration** section and choose **Edit**.

1. In the **Multi-agent collaboration** page, in the **Collaboration status** section, turn on **Multi-agent collaboration**. This will identify the agent as a supervisor agent.

1. In the **Collaboration configuration** section, choose how you want the supervisor agent to handle information across multiple collaborator agents to coordinate a final response.

   1. If you want supervisor agent to coordinate responses from the collaborator agents, select **Supervisor**.

   1. If you want supervisor agent to route information to the appropriate collaborator agent to send the final response, select **Supervisor with routing**.

   1. Continue with the next steps to add collaborator agents.

**Step 3: Add collaborator agents**

1. Expand the **Agent collaborator** section and provide details of the collaborator agent you created for multi-agent collaboration.

   1. For **Collaborator agent**, select a collaborator agent and **Agent alias**from the drop-down. You can choose **View** to view the details of the collaborator agent.

   1. For **Collaborator name**, enter an alternate name for your collaborator agent. This name will not replace the original name of this agent.

   1. In **Collaboration instructions**, enter the details for when this collaborator should be used by the supervisor agent. 

   1. (Optional) Turn on **Enable conversation history** if you want the supervisor agent to share context from previous conversations with this collaborator agent. If this is turned on, the supervisor will include the full history of the current session, including the user input text and the supervisor agent response from each turn of the conversation.

1. Choose **Add collaborator** to add this collaborator agent in your multi-agent-collaboration team. To add more collaborator agents, repeat step 1 until you've added all your collaborator agents. 

1. When you've finished adding collaborator agents, select one of the following options:
   + To stay in the **Multi-agent collaboration**, choose **Save** and continue with the next step to prepare and test your multi-agents collaboration team.
   + To return to the **Agent Details** page, choose **Save and exit**.

**Step 4: Prepare and test a multi-agent collaboration**
+ Follow instructions to [prepare and test](agents-test.md) your multi-agent collaboration team. 

**Step 5: Deploy a multi-agent collaboration**
+ [Deploy](agents-deploy.md) multi-agent collaboration by setting up the supervisor agent to make an `InvokeAgent` request.

------
#### [ API ]

Complete the following steps to create a multi-agent collaboration team,

**Step 1: Create collaborator agents**
+ Follow instructions to [Create and configure an agent](https://docs.aws.amazon.com//bedrock/latest/userguide/agents-create.html). Make sure to configure each collaborator agent to perform a specific task.

**Step 2: Create a new supervisor agent or assign supervisor role to an existing agent**
+ To create a new supervisor agent, send a [https://docs.aws.amazon.com/bedrock/latest/APIReference/API_agent_CreateAgent.html](https://docs.aws.amazon.com/bedrock/latest/APIReference/API_agent_CreateAgent.html) request (see link for request and response formats and field details) with an [Agents for Amazon Bedrock build-time endpoint](https://docs.aws.amazon.com/general/latest/gr/bedrock.html#bra-bt).

  To assign a supervisor role to an existing agent, send an [https://docs.aws.amazon.com/bedrock/latest/APIReference/API_agent_UpdateAgent.html](https://docs.aws.amazon.com/bedrock/latest/APIReference/API_agent_UpdateAgent.html) request with an [Agents for Amazon Bedrock build-time endpoint](https://docs.aws.amazon.com/general/latest/gr/bedrock.html#bra-bt). Because all fields will be overwritten, include both fields that you want to update as well as fields that you want to keep the same.

  You must minimally include the following fields:  
****    
[\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/bedrock/latest/userguide/create-multi-agent-collaboration.html)

  The following fields are optional:  
****    
[\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/bedrock/latest/userguide/create-multi-agent-collaboration.html)

  The response returns an [https://docs.aws.amazon.com/bedrock/latest/APIReference/API_agent_Agent.html](https://docs.aws.amazon.com/bedrock/latest/APIReference/API_agent_Agent.html) object that contains details about your newly created supervisor agent. If your agent fails to be created, the [https://docs.aws.amazon.com/bedrock/latest/APIReference/API_agent_Agent.html](https://docs.aws.amazon.com/bedrock/latest/APIReference/API_agent_Agent.html) object in the response returns a list of `failureReasons` and a list of `recommendedActions` for you to troubleshoot.

**Step 3: Add collaborator agents**
+ To associate collaborator agents with the supervisor agent, send a `AssociateAgentCollaborator` request (see link for request and response formats and field details) with an [Agents for Amazon Bedrock build-time endpoint](https://docs.aws.amazon.com/general/latest/gr/bedrock.html#bra-bt).

  You must minimally include the following fields:  
****    
[\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/bedrock/latest/userguide/create-multi-agent-collaboration.html)

**Step 4: Prepare and test your multi-agent collaborator team**
+ Follow instructions to [prepare and test](agents-test.md) your multi-agent collaboration team. 

**Step 4: Deploy your multi-agent collaboration team**
+ [Deploy](agents-deploy.md) your multi-agent collaboration team by setting up your supervisor agent to make an `InvokeAgent` request.

------

# Disassociate collaborator agent
<a name="disassociate-collaborator-agent"></a>

You can disassociate one or more collaborator agents from the supervisor agent in the Amazon Bedrock console, using the APIs, using the AWS CLI, or by using the AWS SDK. To learn how to disassociate a collaborator agent choose the tab for your preferred method, and then follow the steps:.

------
#### [ Console ]

**To disassociate collaborator agent from the supervisor agent,**

1. If you're not already in the agent builder, do the following:

   1. Sign in to the AWS Management Console with an IAM identity that has permissions to use the Amazon Bedrock console. Then, open the Amazon Bedrock console at [https://console.aws.amazon.com/bedrock](https://console.aws.amazon.com/bedrock).

   1. Select **Agents** from the left navigation pane. Then, choose an agent in the **Agents** section.

   1. Choose **Edit in Agent builder**.

1. In the **Agent builder**, scroll down to the **Multi-agent collaboration** section and choose **Edit**.

1. In the **Multi-agent collaboration** page, choose **Expand all**.

1. In the **Agent collaborator** sections, go to the collaborator agent section you want to disassociate and choose the trash can icon.

1. After you've finished disassociating collaborator agents, choose **Save** and then **Prepare** to test your updated multi-agent collaboration configurations. To learn how to test your multi-agent collaboration team, see [Test and troubleshoot agent behavior](agents-test.md).

1. To return to the **Agent Details** page, choose **Save and exit**.

------
#### [ API ]

To disassociate a collaborator agent, send an `DisassociateAgentCollaborator` request with an [Agents for Amazon Bedrock build-time endpoint](https://docs.aws.amazon.com/general/latest/gr/bedrock.html#bra-bt). Because all fields will be overwritten, include both fields that you want to update as well as fields that you want to keep the same..

To apply the changes to the working draft, send a [https://docs.aws.amazon.com/bedrock/latest/APIReference/API_agent_PrepareAgent.html](https://docs.aws.amazon.com/bedrock/latest/APIReference/API_agent_PrepareAgent.html) request with an [Agents for Amazon Bedrock build-time endpoint](https://docs.aws.amazon.com/general/latest/gr/bedrock.html#bra-bt). Include the `agentId` in the request. The changes apply to the `DRAFT` version, which the `TSTALIASID` alias points to.

You must minimally include the following fields:


****  

| Field | Use case | 
| --- | --- | 
| agentId | The agent ID. | 
| agentVersion | The agent version. | 
| collaboratorId | The collaborator agent ID. | 

------

# Disable a multi-agent collaboration
<a name="disable-multi-agents-collaboration"></a>

You can disable multi-agent collaboration at any time. Before you disable multi-agent collaboration, make sure that you've [disassociated all collaborator agents](disassociate-collaborator-agent.md) that are associated with the supervisor agent.

You can disable multi-agent collaboration in the Amazon Bedrock console, using the APIs, using the AWS CLI, or by using the AWS SDK. To learn how to create a multi-agent collaboration, choose the tab for your preferred method, and then follow the steps:.

------
#### [ Console ]

**To disable multi-agent collaboration,**

1. If you're not already in the agent builder, do the following:

   1. Sign in to the AWS Management Console with an IAM identity that has permissions to use the Amazon Bedrock console. Then, open the Amazon Bedrock console at [https://console.aws.amazon.com/bedrock](https://console.aws.amazon.com/bedrock).

   1. Select **Agents** from the left navigation pane. Then, choose an agent in the **Agents** section.

   1. Choose **Edit in Agent builder**.

1. In the **Agent builder**, scroll down to the **Multi-agent collaboration** section and choose **Edit**.

1. In the **Multi-agent collaboration** page, in the **Collaboration status** section, turn off **Multi-agent collaboration**. This agent is no longer associated with any other agents. You can continue to use this agent as a stand-alone agent.

1. After you've finished disabling multi-agent collaboration, choose **Save** and then **Prepare** to test your updated agent configurations. To learn how to test your updated agent configurations, see [Test and troubleshoot agent behavior](agents-test.md).

1. To return to the **Agent Details** page, choose **Save and exit**.

------
#### [ API ]

To disable multi-agent collaboration, send an [https://docs.aws.amazon.com/bedrock/latest/APIReference/API_agent_UpdateAgent.html](https://docs.aws.amazon.com/bedrock/latest/APIReference/API_agent_UpdateAgent.html) request with an [Agents for Amazon Bedrock build-time endpoint](https://docs.aws.amazon.com/general/latest/gr/bedrock.html#bra-bt). Because all fields will be overwritten, include both fields that you want to update as well as fields that you want to keep the same.

To apply the changes to the working draft, send a [https://docs.aws.amazon.com/bedrock/latest/APIReference/API_agent_PrepareAgent.html](https://docs.aws.amazon.com/bedrock/latest/APIReference/API_agent_PrepareAgent.html) request with an [Agents for Amazon Bedrock build-time endpoint](https://docs.aws.amazon.com/general/latest/gr/bedrock.html#bra-bt). Include the `agentId` in the request. The changes apply to the `DRAFT` version, which the `TSTALIASID` alias points to.

You must minimally include the following fields:


****  

| Field | Use case | 
| --- | --- | 
| agentResourceRoleArn | To specify an ARN of the service role with permissions to call API operations on the agent | 
| foundationModel | To specify a foundation model (FM) for the agent to orchestrate with | 
| instruction | To provide instructions to tell the agent what to do. Used in the \$1instructions\$1 placeholder of the orchestration prompt template. | 
| agentCollaboration |  To disable multi-agent collaboration, set this field to `DISABLED`  | 

------