Amazon Bedrock Agents Integration

This tutorial walks you through the process of integrating Amazon Bedrock Agents and Flows into Solace Agent Mesh (SAM). This integration allows you to create agents that can interact with one or multiple Bedrock Agents or Flows, extending your SAM project with powerful AI capabilities from AWS.

What are Amazon Bedrock Agents and Flows?

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.

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.

By integrating these services with SAM, you can:

Use the extensible SAM framework to combine Bedrock agents and flows with other agents.
Create conversational interfaces that leverage Bedrock agents and flows.
Connect your SAM agents to enterprise data sources through Bedrock.
Maintain a consistent experience across different agent providers by centralizing them in SAM.

Learn about Bedrock Agents and Flows

Check the official documentation for Amazon Bedrock Agents and Amazon Bedrock Flows to learn more about these features.

Setting Up the Environment

Create Bedrock Agents and Flows

Follow these steps to create your Bedrock resources:

Log in to your AWS console
- Navigate to the Amazon Bedrock service
Create Bedrock Agents
- Go to the Agents tab in the Bedrock console
- Click "Create agent"
- Follow the wizard to configure your agent:
  - Select a foundation model
  - Define the agent's instructions
  - Configure knowledge bases (optional)
  - Set up action groups (if needed)
- Once created, create an alias for your agent by selecting it and clicking "Create alias"
- Copy the Agent ID and Alias ID from the agent details page - you'll need these for the SAM configuration
Create Bedrock Flows
- Go to the Flows tab in the Bedrock console
- Click "Create flow"
- Use the visual editor to design your flow
- Connect nodes to create your workflow
- Test and publish your flow
- Create an alias for your flow
- Copy the Flow ID and Alias ID - you'll need these for the SAM configuration
Set up IAM permissions
- Ensure your IAM user or role has the following permissions:
  - bedrock:InvokeAgent
  - bedrock:InvokeFlow
  - Any other permissions required by your specific Bedrock configuration

Create a SAM Project

You must install Solace Agent Mesh and Solace Mesh Agent (SAM) CLI, and then you'll want to create a new Solace Agent Mesh project.

Integrating Bedrock with SAM

Adding the Bedrock Agent Plugin

The sam-bedrock-agent plugin from the solace-agent-mesh-core-plugins repository creates a bridge between SAM and Amazon Bedrock services. This plugin allows your SAM agents to invoke Bedrock Agents and Flows as tools.

Add the plugin to your SAM project:

sam plugin add aws-agent --plugin sam-bedrock-agent

Replace aws-agent with a descriptive name for your agent, such as bedrock-summarizer or bedrock-customer-service.

This command:

Installs the sam-bedrock-agent plugin
Creates a new agent configuration file in configs/agents/aws-agent.yaml

Locate the configuration file:

The command creates an aws-agent.yaml file in the configs/agents/ directory of your SAM project.

Naming Convention

Choose a descriptive name that reflects the purpose of your Bedrock integration. This name is used to reference the agent in your SAM project.

Configuring the Bedrock Agent

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.

Understanding the Configuration Structure

Open the aws-agent.yaml file in your editor. The core of the agent's configuration consists of:

amazon_bedrock_runtime_config: AWS connection settings
tools: List of Bedrock agents and flows to expose as tools
agent_card: Agent capabilities and skills definition

Example Configuration

Here's an annotated example based on the actual plugin structure:

log:
  stdout_log_level: INFO
  log_file_level: DEBUG
  log_file: aws-agent.log

!include ../shared_config.yaml

apps:
  - name: aws-agent-app
    app_base_path: . 
    app_module: solace_agent_mesh.agent.sac.app 
    broker:
      <<: *broker_connection

    app_config:
      namespace: ${NAMESPACE} 
      supports_streaming: true 
      agent_name: "AwsAgent" 
      display_name: "AwsAgent Component" 
      model: *general_model 

      instruction: |
        You're AwsAgent responsible for handling user queries by 
        interacting with Amazon Bedrock agents or flows.

      # AWS Connection Configuration
      amazon_bedrock_runtime_config: &amazon_bedrock_runtime_config
        endpoint_url: # Optional: Custom AWS endpoint URL
        boto3_config:
          region_name: "us-east-1" # AWS region where your Bedrock resources are located
          aws_access_key_id: # Your AWS access key (or use profiles/env vars)
          aws_secret_access_key: # Your AWS secret key

      tools:
        # Bedrock Agent Tool
        - tool_type: python
          component_module: sam_bedrock_agent.bedrock_agent
          component_base_path: . 
          function_name: invoke_bedrock_agent
          tool_name: "text_transformer" # Customizable, Name exposed to the LLM
          tool_description: "Transforms text using the Text Transformer agent which summarizes the given text and extracts key points." # Customizable, Optional description
          tool_config:
            amazon_bedrock_runtime_config: *amazon_bedrock_runtime_config
            bedrock_agent_id: "XXXXXXXXXX" # Your actual Bedrock agent ID
            bedrock_agent_alias_id: "XXXXXXXXXX" # Your actual Bedrock agent alias ID
            allow_files: true # Whether to allow file uploads (5 files, 10MB total max)

        # Bedrock Flow Tool
        - tool_type: python
          component_module: sam_bedrock_agent.bedrock_flow
          component_base_path: .
          function_name: invoke_bedrock_flow
          tool_name: "poem_writer" # Name exposed to the LLM
          tool_config: 
            amazon_bedrock_runtime_config: *amazon_bedrock_runtime_config
            bedrock_flow_id: "XXXXXXXXXX" # Your actual Bedrock flow ID
            bedrock_flow_alias_id: "XXXXXXXXXX" # Your actual Bedrock flow alias ID

      # Agent capabilities
      agent_card:
        description: "Agent that integrates with Amazon Bedrock agents and flows for various AI tasks."
        defaultInputModes: ["text"]
        defaultOutputModes: ["text"]
        skills: 
          - id: "text_transformer"
            name: "Text Transformer"
            description: "Transforms text using the Text Transformer agent."
          - id: "poem_writer"
            name: "Poem Writer"
            description: "Generates poems based on user input."

      # A2A Protocol settings
      agent_card_publishing: { interval_seconds: 10 }
      agent_discovery: { enabled: true }
      inter_agent_communication:
        allow_list: ["*"]
        request_timeout_seconds: 30

Customizing Your Configuration

Follow these steps to customize your configuration:

Configure AWS Connection:
- Set the region_name to the AWS region where your Bedrock resources are located
- Choose one of these authentication methods:
  - Set aws_access_key_id and aws_secret_access_key directly in the config.
  - Use AWS profiles by removing these fields and configuring your AWS CLI profile.
  - Use environment variables (see Environment Variables section below).

Check the boto3 documentation for more details.

Configure Bedrock Agent Tools:
- For each Bedrock agent you want to expose, add a tool entry:
  - Set a descriptive tool_name (for example, text_summarizer, content_generator).
  - Provide a clear tool_description of what the agent does.
  - Replace bedrock_agent_id with your actual Bedrock agent ID.
  - Replace bedrock_agent_alias_id with your actual Bedrock agent alias ID.
  - Set allow_files to true if your agent can process file uploads.
Configure Bedrock Flow Tools:
- For each Bedrock flow you want to expose, add a tool entry:
  - Set a descriptive tool_name for the flow.
  - Provide a clear tool_description of what the flow does (optional).
  - Replace bedrock_flow_id with your actual Bedrock flow ID.
  - Replace bedrock_flow_alias_id with your actual Bedrock flow alias ID.
Update Agent Card Skills:
- Update the agent_card.description to reflect the purpose of your Bedrock agent (This is what other agents see).
- For each tool you add, create a corresponding skill entry in the agent_card.skills section.
- Use the same id as the tool_name.
- Provide a user-friendly name and description.
Update Agent Instructions:
- Modify the instruction field to provide clear guidance on how the agent should respond to user queries.
- This instruction is used by the Agent's LLM to understand its role and capabilities.

info

You must provide at least one Bedrock agent or flow tool. You can mix and match agents and flows in the same configuration.

Environment Variables

The Bedrock agent integration requires standard Solace connection variables and can use AWS environment variables for authentication.

Required Solace Variables:

SOLACE_BROKER_URL: URL of your Solace broker
SOLACE_BROKER_USERNAME: Username for Solace broker authentication
SOLACE_BROKER_PASSWORD: Password for Solace broker authentication
SOLACE_BROKER_VPN: Solace message VPN name
SOLACE_AGENT_MESH_NAMESPACE: Namespace for your SAM project

Optional AWS Variables:

If you prefer to use environment variables for AWS authentication instead of configuration in the YAML file:

AWS_ACCESS_KEY_ID: Your AWS access key
AWS_SECRET_ACCESS_KEY: Your AWS secret key
AWS_SESSION_TOKEN: If using temporary credentials
AWS_REGION or AWS_DEFAULT_REGION: AWS region for Bedrock services

AWS Credentials Precedence

AWS credentials are loaded in this order:

Explicit credentials in the YAML configuration
Environment variables
AWS configuration files (~/.aws/credentials)
EC2/ECS instance profiles (if running on AWS)

Running and Testing Your Integration

Starting Your SAM Project

After configuring your Bedrock agent integration, run your SAM project:

sam run configs/agents/aws-agent.yaml

This command starts the Bedrock agent with your specific configuration.

Testing the Integration

You can test your Bedrock agent integration through any gateway in your SAM project:

Using the Web UI Gateway

Ensure you have a Web UI gateway running (typically at http://localhost:8000)
Start a conversation with your agent
Ask a question that would trigger your Bedrock agent or flow

Example: If you configured a Bedrock agent for text transformation:

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."

Example: If you configured a Bedrock flow for poem writing:

Write a poem about a sunset over the ocean.

Testing with File Uploads

If you have enabled file uploads for your Bedrock agent (allow_files: true), you can test file processing:

In the Web UI, use the file upload button to attach a supported file
Include a prompt that references the file, such as "Analyze this document" or "Summarize the content of this file"
The file is sent to the Bedrock agent along with your prompt

Example with file upload:

Please analyze the attached document and provide key insights.

Supported File Types

Bedrock agents support these file types for uploads:

PDF documents (.pdf)
Text files (.txt)
Word documents (.doc, .docx)
CSV files (.csv)
Excel spreadsheets (.xls, .xlsx)

There's a limit of 5 files with a total size of 10MB per request.

Troubleshooting

Common Issues and Solutions

Authentication Errors

Issue: "Unable to locate credentials" or "Access denied" errors Solution:

Verify your AWS credentials are correctly configured
Check that your IAM user/role has the necessary permissions
Try using AWS CLI to test your credentials: aws bedrock list-foundation-models

Configuration Errors

Issue: "Invalid agent ID" or "Invalid flow ID" errors Solution:

Double-check your Bedrock agent and flow IDs in the configuration
Ensure you've created aliases for your agents and flows
Verify the region in your configuration matches where your Bedrock resources are located

Connection Issues

Issue: SAM can't connect to Bedrock services Solution:

Check your network connectivity
Verify that Bedrock services are available in your configured region
Check for any VPC or firewall restrictions

File Upload Issues

Issue: Files aren't being processed by the Bedrock agent Solution:

Verify allow_files is set to true in your configuration
Check that your file type is supported
Ensure the file size is under the 10MB limit
Check the model context length

What are Amazon Bedrock Agents and Flows?​

Setting Up the Environment​

Create Bedrock Agents and Flows​

Create a SAM Project​

Integrating Bedrock with SAM​

Adding the Bedrock Agent Plugin​

Configuring the Bedrock Agent​

Understanding the Configuration Structure​

Example Configuration​

Customizing Your Configuration​

Environment Variables​

Required Solace Variables:​

Optional AWS Variables:​

Running and Testing Your Integration​

Starting Your SAM Project​

Testing the Integration​

Using the Web UI Gateway​

Testing with File Uploads​

Troubleshooting​

Common Issues and Solutions​

Authentication Errors​

Configuration Errors​

Connection Issues​

File Upload Issues​