bedrock-agents.md
1 --- 2 title: Amazon Bedrock Agents 3 sidebar_position: 30 4 toc_max_heading_level: 4 5 --- 6 7 # Amazon Bedrock Agents Integration 8 9 This tutorial walks you through the process of integrating Amazon Bedrock Agents and Flows into Agent Mesh. This integration allows you to create agents that can interact with one or multiple Bedrock Agents or Flows, extending your Agent Mesh project with powerful AI capabilities from AWS. 10 11 ## What are Amazon Bedrock Agents and Flows? 12 13 Amazon Bedrock Agents are AI assistants that can be customized to perform specific tasks using foundation models (FMs). They can connect to enterprise systems and data sources, allowing them to take actions on behalf of users. 14 15 Amazon Bedrock Flows are visual workflows that orchestrate multiple foundation models to solve complex problems. They allow you to chain together different AI capabilities without writing code. 16 17 By integrating these services with Agent Mesh, you can: 18 - Use the extensible Agent Mesh framework to combine Bedrock agents and flows with other agents. 19 - Create conversational interfaces that leverage Bedrock agents and flows. 20 - Connect your Agent Mesh agents to enterprise data sources through Bedrock. 21 - Maintain a consistent experience across different agent providers by centralizing them in Agent Mesh. 22 23 :::info[Learn about Bedrock Agents and Flows] 24 Check the official documentation for [Amazon Bedrock Agents](https://aws.amazon.com/bedrock/agents/) and [Amazon Bedrock Flows](https://aws.amazon.com/bedrock/flows/) to learn more about these features. 25 ::: 26 27 28 ## Setting Up the Environment 29 30 ### Create Bedrock Agents and Flows 31 32 Follow these steps to create your Bedrock resources: 33 34 1. **Log in to your AWS console** 35 - Navigate to the Amazon Bedrock service 36 37 2. **Create Bedrock Agents** 38 - Go to the **Agents** tab in the Bedrock console 39 - Click "Create agent" 40 - Follow the wizard to configure your agent: 41 - Select a foundation model 42 - Define the agent's instructions 43 - Configure knowledge bases (optional) 44 - Set up action groups (if needed) 45 - Once created, **create an alias** for your agent by selecting it and clicking "Create alias" 46 - **Copy the Agent ID and Alias ID** from the agent details page - you'll need these for the Agent Mesh configuration 47 48 3. **Create Bedrock Flows** 49 - Go to the **Flows** tab in the Bedrock console 50 - Click "Create flow" 51 - Use the visual editor to design your flow 52 - Connect nodes to create your workflow 53 - Test and publish your flow 54 - **Create an alias** for your flow 55 - **Copy the Flow ID and Alias ID** - you'll need these for the Agent Mesh configuration 56 57 4. **Set up IAM permissions** 58 - Ensure your IAM user or role has the following permissions: 59 - `bedrock:InvokeAgent` 60 - `bedrock:InvokeFlow` 61 - Any other permissions required by your specific Bedrock configuration 62 63 ### Create an Agent Mesh Project 64 65 You must [install Agent Mesh and Solace Mesh Agent CLI](../../installing-and-configuring/installation.md), and then you'll want to [create a new Agent Mesh project](../../installing-and-configuring/run-project.md). 66 67 68 ## Integrating Bedrock with Agent Mesh 69 70 ### Adding the Bedrock Agent Plugin 71 72 The `sam-bedrock-agent` plugin from the [solace-agent-mesh-core-plugins](https://github.com/SolaceLabs/solace-agent-mesh-core-plugins/tree/main/sam-bedrock-agent) repository creates a bridge between Agent Mesh and Amazon Bedrock services. This plugin allows your Agent Mesh agents to invoke Bedrock Agents and Flows as tools. 73 74 1. **Add the plugin to your Agent Mesh project**: 75 76 ```sh 77 sam plugin add aws-agent --plugin sam-bedrock-agent 78 ``` 79 80 Replace `aws-agent` with a descriptive name for your agent, such as `bedrock-summarizer` or `bedrock-customer-service`. 81 82 This command: 83 - Installs the `sam-bedrock-agent` plugin 84 - Creates a new agent configuration file in `configs/agents/aws-agent.yaml` 85 86 87 2. **Locate the configuration file**: 88 89 The command creates an `aws-agent.yaml` file in the `configs/agents/` directory of your Agent Mesh project. 90 91 :::tip[Naming Convention] 92 Choose a descriptive name that reflects the purpose of your Bedrock integration. This name is used to reference the agent in your Agent Mesh project. 93 ::: 94 95 ## Configuring the Bedrock Agent 96 97 The configuration file you created needs to be edited to connect to your specific Amazon Bedrock resources. This section explains each part of the configuration and how to customize it. 98 99 ### Understanding the Configuration Structure 100 101 Open the `aws-agent.yaml` file in your editor. The core of the agent's configuration consists of: 102 103 1. **amazon_bedrock_runtime_config**: AWS connection settings 104 2. **tools**: List of Bedrock agents and flows to expose as tools 105 3. **agent_card**: Agent capabilities and skills definition 106 107 ### Example Configuration 108 109 Here's an annotated example based on the actual plugin structure: 110 111 ```yaml 112 log: 113 stdout_log_level: INFO 114 log_file_level: DEBUG 115 log_file: aws-agent.log 116 117 !include ../shared_config.yaml 118 119 apps: 120 - name: aws-agent-app 121 app_base_path: . 122 app_module: solace_agent_mesh.agent.sac.app 123 broker: 124 <<: *broker_connection 125 126 app_config: 127 namespace: ${NAMESPACE} 128 supports_streaming: true 129 agent_name: "AwsAgent" 130 display_name: "AwsAgent Component" 131 model: *general_model 132 model_provider: 133 - "general" 134 135 instruction: | 136 You're AwsAgent responsible for handling user queries by 137 interacting with Amazon Bedrock agents or flows. 138 139 # AWS Connection Configuration 140 amazon_bedrock_runtime_config: &amazon_bedrock_runtime_config 141 endpoint_url: # Optional: Custom AWS endpoint URL 142 boto3_config: 143 region_name: "us-east-1" # AWS region where your Bedrock resources are located 144 aws_access_key_id: # Your AWS access key (or use profiles/env vars) 145 aws_secret_access_key: # Your AWS secret key 146 147 tools: 148 # Bedrock Agent Tool 149 - tool_type: python 150 component_module: sam_bedrock_agent.bedrock_agent 151 component_base_path: . 152 function_name: invoke_bedrock_agent 153 tool_name: "text_transformer" # Customizable, Name exposed to the LLM 154 tool_description: "Transforms text using the Text Transformer agent which summarizes the given text and extracts key points." # Customizable, Optional description 155 tool_config: 156 amazon_bedrock_runtime_config: *amazon_bedrock_runtime_config 157 bedrock_agent_id: "XXXXXXXXXX" # Your actual Bedrock agent ID 158 bedrock_agent_alias_id: "XXXXXXXXXX" # Your actual Bedrock agent alias ID 159 allow_files: true # Whether to allow file uploads (5 files, 10MB total max) 160 161 # Bedrock Flow Tool 162 - tool_type: python 163 component_module: sam_bedrock_agent.bedrock_flow 164 component_base_path: . 165 function_name: invoke_bedrock_flow 166 tool_name: "poem_writer" # Name exposed to the LLM 167 tool_config: 168 amazon_bedrock_runtime_config: *amazon_bedrock_runtime_config 169 bedrock_flow_id: "XXXXXXXXXX" # Your actual Bedrock flow ID 170 bedrock_flow_alias_id: "XXXXXXXXXX" # Your actual Bedrock flow alias ID 171 172 # Agent capabilities 173 agent_card: 174 description: "Agent that integrates with Amazon Bedrock agents and flows for various AI tasks." 175 defaultInputModes: ["text"] 176 defaultOutputModes: ["text"] 177 skills: 178 - id: "text_transformer" 179 name: "Text Transformer" 180 description: "Transforms text using the Text Transformer agent." 181 - id: "poem_writer" 182 name: "Poem Writer" 183 description: "Generates poems based on user input." 184 185 # A2A Protocol settings 186 agent_card_publishing: { interval_seconds: 10 } 187 agent_discovery: { enabled: true } 188 inter_agent_communication: 189 allow_list: ["*"] 190 request_timeout_seconds: 30 191 ``` 192 193 ### Customizing Your Configuration 194 195 Follow these steps to customize your configuration: 196 197 1. **Configure AWS Connection**: 198 - Set the `region_name` to the AWS region where your Bedrock resources are located 199 - Choose one of these authentication methods: 200 - Set `aws_access_key_id` and `aws_secret_access_key` directly in the config. 201 - Use AWS profiles by removing these fields and configuring your AWS CLI profile. 202 - Use environment variables (see Environment Variables section below). 203 204 Check the [boto3 documentation](https://boto3.amazonaws.com/v1/documentation/api/latest/reference/core/session.html) for more details. 205 206 2. **Configure Bedrock Agent Tools**: 207 - For each Bedrock agent you want to expose, add a tool entry: 208 - Set a descriptive `tool_name` (for example, `text_summarizer`, `content_generator`). 209 - Provide a clear `tool_description` of what the agent does. 210 - Replace `bedrock_agent_id` with your actual Bedrock agent ID. 211 - Replace `bedrock_agent_alias_id` with your actual Bedrock agent alias ID. 212 - Set `allow_files` to `true` if your agent can process file uploads. 213 214 3. **Configure Bedrock Flow Tools**: 215 - For each Bedrock flow you want to expose, add a tool entry: 216 - Set a descriptive `tool_name` for the flow. 217 - Provide a clear `tool_description` of what the flow does (optional). 218 - Replace `bedrock_flow_id` with your actual Bedrock flow ID. 219 - Replace `bedrock_flow_alias_id` with your actual Bedrock flow alias ID. 220 221 4. **Update Agent Card Skills**: 222 - Update the `agent_card.description` to reflect the purpose of your Bedrock agent (This is what other agents see). 223 - For each tool you add, create a corresponding skill entry in the `agent_card.skills` section. 224 - Use the same `id` as the `tool_name`. 225 - Provide a user-friendly `name` and `description`. 226 227 5. **Update Agent Instructions**: 228 - Modify the `instruction` field to provide clear guidance on how the agent should respond to user queries. 229 - This instruction is used by the Agent's LLM to understand its role and capabilities. 230 231 :::info 232 You must provide at least one Bedrock agent or flow tool. You can mix and match agents and flows in the same configuration. 233 ::: 234 235 ### Environment Variables 236 237 The Bedrock agent integration requires standard Solace connection variables and can use AWS environment variables for authentication. 238 239 #### Required Solace Variables: 240 - **SOLACE_BROKER_URL**: URL of your Solace broker 241 - **SOLACE_BROKER_USERNAME**: Username for Solace broker authentication 242 - **SOLACE_BROKER_PASSWORD**: Password for Solace broker authentication 243 - **SOLACE_BROKER_VPN**: Solace message VPN name 244 - **SOLACE_AGENT_MESH_NAMESPACE**: Namespace for your Agent Mesh project 245 246 #### Optional AWS Variables: 247 If you prefer to use environment variables for AWS authentication instead of configuration in the YAML file: 248 - **AWS_ACCESS_KEY_ID**: Your AWS access key 249 - **AWS_SECRET_ACCESS_KEY**: Your AWS secret key 250 - **AWS_SESSION_TOKEN**: If using temporary credentials 251 - **AWS_REGION** or **AWS_DEFAULT_REGION**: AWS region for Bedrock services 252 253 :::tip[AWS Credentials Precedence] 254 AWS credentials are loaded in this order: 255 1. Explicit credentials in the YAML configuration 256 2. Environment variables 257 3. AWS configuration files (~/.aws/credentials) 258 4. EC2/ECS instance profiles (if running on AWS) 259 ::: 260 261 ## Running and Testing Your Integration 262 263 ### Starting Your Agent Mesh Project 264 265 After configuring your Bedrock agent integration, run your Agent Mesh project: 266 267 ```sh 268 sam run configs/agents/aws-agent.yaml 269 ``` 270 271 This command starts the Bedrock agent with your specific configuration. 272 273 ### Testing the Integration 274 275 You can test your Bedrock agent integration through any gateway in your Agent Mesh project: 276 277 #### Using the Web UI Gateway 278 279 1. Ensure you have a Web UI gateway running (typically at http://localhost:8000) 280 2. Start a conversation with your agent 281 3. Ask a question that would trigger your Bedrock agent or flow 282 283 **Example**: If you configured a Bedrock agent for text transformation: 284 ``` 285 Transform this text: "The quick brown fox jumps over the lazy dog. The lazy dog did not chase the fox. The fox was brown and quick, while the dog was lazy and slow. Despite their differences, they both enjoyed the sunny day in the meadow." 286 ``` 287 288 **Example**: If you configured a Bedrock flow for poem writing: 289 ``` 290 Write a poem about a sunset over the ocean. 291 ``` 292 293 #### Testing with File Uploads 294 295 If you have enabled file uploads for your Bedrock agent (`allow_files: true`), you can test file processing: 296 297 1. In the Web UI, use the file upload button to attach a supported file 298 2. Include a prompt that references the file, such as "Analyze this document" or "Summarize the content of this file" 299 3. The file is sent to the Bedrock agent along with your prompt 300 301 **Example with file upload**: 302 ``` 303 Please analyze the attached document and provide key insights. 304 ``` 305 306 :::info[Supported File Types] 307 Bedrock agents support these file types for uploads: 308 - PDF documents (.pdf) 309 - Text files (.txt) 310 - Word documents (.doc, .docx) 311 - CSV files (.csv) 312 - Excel spreadsheets (.xls, .xlsx) 313 314 There's a limit of 5 files with a total size of 10MB per request. 315 ::: 316 317 ## Troubleshooting 318 319 ### Common Issues and Solutions 320 321 #### Authentication Errors 322 323 **Issue**: "Unable to locate credentials" or "Access denied" errors 324 **Solution**: 325 - Verify your AWS credentials are correctly configured 326 - Check that your IAM user/role has the necessary permissions 327 - Try using AWS CLI to test your credentials: `aws bedrock list-foundation-models` 328 329 #### Configuration Errors 330 331 **Issue**: "Invalid agent ID" or "Invalid flow ID" errors 332 **Solution**: 333 - Double-check your Bedrock agent and flow IDs in the configuration 334 - Ensure you've created aliases for your agents and flows 335 - Verify the region in your configuration matches where your Bedrock resources are located 336 337 #### Connection Issues 338 339 **Issue**: Agent Mesh can't connect to Bedrock services 340 **Solution**: 341 - Check your network connectivity 342 - Verify that Bedrock services are available in your configured region 343 - Check for any VPC or firewall restrictions 344 345 #### File Upload Issues 346 347 **Issue**: Files aren't being processed by the Bedrock agent 348 **Solution**: 349 - Verify `allow_files` is set to `true` in your configuration 350 - Check that your file type is supported 351 - Ensure the file size is under the 10MB limit 352 - Check the model context length