AWS solutions documentation change
Summary
Added documentation for expanding supported Strands tools including configuration steps for SSM parameters, environment variables, IAM permissions, and testing procedures
Security assessment
The change adds security documentation through IAM permission requirements for tools like Bedrock Knowledge Base access, but does not address a specific security vulnerability. It provides guidance on secure configuration practices.
Diff
diff --git a/solutions/latest/generative-ai-application-builder-on-aws/integration-guide.md b/solutions/latest/generative-ai-application-builder-on-aws/integration-guide.md index 540307ec9..72a37023f 100644 --- a//solutions/latest/generative-ai-application-builder-on-aws/integration-guide.md +++ b//solutions/latest/generative-ai-application-builder-on-aws/integration-guide.md @@ -5 +5 @@ -Expanding supported LLMsExpanding supported knowledge bases and conversation memory typesBuilding and deploying the code changes +Expanding supported LLMsExpanding supported Strands toolsExpanding supported knowledge bases and conversation memory typesBuilding and deploying the code changes @@ -71,0 +72,122 @@ You can also use the `get_clean_model_params` method to sanitize the model param +## Expanding supported Strands tools + +The Solution enables you to build and deploy MCP servers, AI agents, and multi-agent workflows. Within the Agent Builder experience, you can attach MCP servers to give your agents additional capabilities. In addition to MCP servers, you can leverage built-in tools provided by [Strands](https://strandsagents.com/latest/documentation/docs/user-guide/concepts/tools/community-tools-package/) (the underlying framework used by the solution). + +Out of the box, the solution comes pre-configured with the following Strands tools: + + * Current Time (enabled by default) + + * Calculator (enabled by default) + + * Environment + + + + +**MCP Server and Tools selection in the Agent Builder wizard showing built-in Strands tools** + + + +To extend your agents with additional Strands tools, follow the four-step process outlined in this section. + +### Step 1: Find the Strands tool + +Browse the [available Strands tools](https://strandsagents.com/latest/documentation/docs/user-guide/concepts/tools/community-tools-package/#available-tools) to identify the tool you want to use. Each tool has specific capabilities and configuration requirements. + +For example, to add Amazon Bedrock Knowledge Base retrieval capabilities, you would use the [retrieve](https://github.com/strands-agents/tools/blob/main/src/strands_tools/retrieve.py) tool. + +### Step 2: Update the SSM parameter + +To make a tool available in the Agent Builder deployment UI, update the AWS Systems Manager Parameter Store parameter that defines which Strands tools are supported. + + 1. Navigate to the AWS Systems Manager Parameter Store in your AWS account. + + 2. Locate the parameter: `/gaab/<stack-name>/strands-tools` + + 3. Add your tool configuration to the end of the existing list using the following JSON structure: + + { + "name": "Bedrock KB Retrieve", + "description": "Retrieve information from Bedrock Knowledge Base", + "value": "retrieve", + "category": "AI", + "isDefault": false + } + +Field | Description +---|--- +**name** | Display name shown in the Agent Builder UI +**description** | Brief description of the tool’s functionality +**value** | The exact tool name as defined in the Strands tools package +**category** | Organizational category for grouping tools in the UI +**isDefault** | Whether the tool should be enabled by default for new agents + + + + +### Step 3: Configure environment variables + +Many Strands tools require environment variables for configuration. You can set these variables in two ways: + +**Option 1: Direct configuration on AgentCore Runtime** + +Update the deployed agent directly on Amazon Bedrock AgentCore Runtime with the required environment variables. + +**Option 2: Model Parameters in the deployment wizard** + +Add environment variables during the Model selection step in the Agent Builder wizard using the Model Parameters section. Environment variables that follow the naming convention `ENV_<ALL_CAPS_TOOL_NAME>_<env_variable_name>` will automatically be loaded at runtime into the agent’s execution environment as `<env_variable_name>`. + +For example: + + * `ENV_RETRIEVE_KNOWLEDGE_BASE_ID` becomes `KNOWLEDGE_BASE_ID` + + * `ENV_RETRIEVE_MIN_SCORE` becomes `MIN_SCORE` + + + + +**Advanced model parameters section showing ENV_RETRIEVE_KNOWLEDGE_BASE_ID configuration** + + + +Refer to the specific tool’s documentation or source code to identify required environment variables. For the retrieve tool, you can find configuration options in the [source code](https://github.com/strands-agents/tools/blob/main/src/strands_tools/retrieve.py#L293). + +### Step 4: Add IAM permissions + +Manually add any necessary IAM permissions to your AgentCore Runtime execution role to allow the agent to use the tool. + +For example, to use the retrieve tool with Amazon Bedrock Knowledge Bases: + + 1. Navigate to the IAM console in your AWS account. + + 2. Locate the AgentCore Runtime execution role for your agent. + + 3. Add the following permission: + + { + "Effect": "Allow", + "Action": "bedrock:Retrieve", + "Resource": "arn:aws:bedrock:region:account-id:knowledge-base/knowledge-base-id" + } + + + + +**IAM console showing the StrandsRetrieveToolKBAccess policy attached to the AgentCore Runtime execution role** + + + +The specific permissions required will vary based on the tool. Consult the tool’s documentation and AWS service documentation to determine the appropriate IAM permissions. + +### Step 5: Test the agent + +After completing the configuration steps, test your agent to verify the tool is working correctly. You should see tool invocations in the agent’s execution logs and responses. + +**Agent successfully using the retrieve tool to answer a question about skate parks** + + + +###### Note + +For a complete list of available Strands tools and their capabilities, refer to the [Strands Community Tools documentation](https://strandsagents.com/latest/documentation/docs/user-guide/concepts/tools/community-tools-package/). +