# Use your app outside of Amazon SageMaker Unified Studio With Amazon Bedrock in SageMaker Unified Studio, you can export the files for an [chat agent app](create-chat-app.md) and a [flow app](create-flows-app.md). This lets you can use the app outside of Amazon SageMaker Unified Studio. When you export an app, Amazon Bedrock in SageMaker Unified Studio exports a zip file with the AWS CloudFormation templates and other files required by your app. To use your app, you need to deploy the CloudFormation templates to an AWS account. The actual contents of the zip file vary on the Amazon Bedrock in SageMaker Unified Studio components that your app uses. After uncompressing the zip file, you deploy the contents of the zip file into your AWS account (or another AWS account, if you prefer). **Important** Once you export your app, it's your responsibility to audit the app files and make sure they are correct. You can use the CloudFormation templates as you wish. An app can include one or more different types of Amazon Bedrock in SageMaker Unified Studio components. For example, a chat agent app could use a guardrail or a knowledge base. When you deploy your app's components, Amazon Bedrock in SageMaker Unified Studio only deploys the AWS infrastructure files. The data source files for a knowledge base and the secrets for a function aren't exported, and you have to configure them during the deployment. After deploying the app to an AWS account, you can run the app as a Node.js app. ## App export files Depending on the composition of your app, the zip package contains some or all of the following files: + **README.md** — Instructions for deploying and running your app. + **function-stack-\$1.json** — CloudFormation template that creates your function component, if any. This includes: + An AWS Lambda [function](https://docs.aws.amazon.com/bedrock/latest/studio-ug/functions.html) for calling the API defined in your OpenAPI schema. + An AWS Secret Manager secret for storing credentials to use when calling your API. This secret contains an empty value, and you are expected to update this secret manually. + **knowledge-base-stack-\$1.json** — AWS CloudFormation template that creates your [Knowledge Base data source](https://docs.aws.amazon.com/bedrock/latest/studio-ug/data-sources.html#data-source-document), if any. This includes an Knowledge Base for Amazon Bedrock configured with your selected data store and vector store. This knowledge base will not have the data you have uploaded in to Amazon Bedrock in SageMaker Unified Studio, and you are expected to provide data files manually. + **flow-stack.json** — CloudFormation template that creates an Amazon Bedrock flows resource. + **guardrails-stack-\$1.json** — CloudFormation template that creates a [guardrail](https://docs.aws.amazon.com/bedrock/latest/studio-ug/guardrails.html) for Amazon Bedrock, if any. + **agent-stack.json** — CloudFormation template that creates an Amazon Bedrock Agent, if any. + **invocation-policy-\$1.json** — CloudFormation template that creates an IAM policy with the runtime permissions that you need to talk to your deployed chat agent app. + ** br-studio-app-stack-\$1.json** — Parent stack that orchestrates the deployment of all AWS CloudFormation stacks included in the zip package. + **deploy-app.sh** — Helper script that you use to deploy your app infrastructure into your AWS account. + **code-snippet.mjs** — Example code snippet that you embed in your code to invoke the app. + **amazon-bedrock-ide-app.mjs** — Standalone Node.js module to quickly test your deployed app. + **aoss-encryption-policy-\$1.json** — AOSS encryption policy necessary to use a Knowledge Base. This encryption policy is automatically created when your chat agent app contains an Amazon Bedrock in SageMaker Unified Studio Knowledge Base. + **provisioning-inline-policy.json** — An example of an AWS IAM policy that contains the permissions required to provision the chat agent app resources. The permissions declared in this policy file are needed when deploying the AWS CloudFormation stacks. You can modify this policy to better suit your needs. You may create a new IAM principal with these policies, or attach these policies to an existing IAM principal in your AWS account. + ** kms-key-policy.json** — An example of an AWS KMS key policy that contains required permissions for encrypting your chat agent app resources. You can modify this key policy to better suit your needs. You may create a new KMS key with this policy, or attach this policy to an existing KMS key in your AWS account. + **api-schema\$1.json** — OpenAPI schema files associated with your function components, if any. **Topics** + [ ## App export files ](#app-export-files) + [ # Export your Amazon Bedrock app ](app-export-chat-app.md) + [ # Deploy an exported Amazon Bedrock app ](app-deploy-app.md) + [ # Run a deployed Amazon Bedrock app ](app-run-app.md) # Export your Amazon Bedrock app Export your app Use the following procedure to export a chat agent app or a flow app to a zip file. You can then use the app outside of Amazon SageMaker Unified Studio. **To export a chat agent app or a flow app** 1. Navigate to the Amazon SageMaker Unified Studio landing page by using the URL from your administrator. 1. Access Amazon SageMaker Unified Studio using your IAM or single sign-on (SSO) credentials. For more information, see [Access Amazon SageMaker Unified Studio](getting-started-access-the-portal.md). 1. If the project that you want to use isn't already open, do the following: 1. Choose the current project at the top of the page. If a project isn't already open, choose **Select a project**. 1. Select **Browse all projects**. 1. In **Projects** select the project that you want to use. 1. Choose the **Build** menu option at the top of the page. 1. In **MACHINE LEARNING & GENERATIVE AI** choose **My apps**. 1. In **Apps** choose the app that you want to export. 1. If you haven't already, choose **Save** to save the app. You can't export an app unless you first save and run the app. 1. On the app page, choose **Export** to export the app. Amazon Bedrock in SageMaker Unified Studio will create and download a zip file with the name **amazon-bedrock-ide-app-export-\$1.zip**. 1. Next step: [Deploy the app](app-deploy-app.md). # Deploy an exported Amazon Bedrock app Deploy an exported app The following instructions show you the steps you take to deploy a chat agent app that you [export](app-export-chat-app.md) from Amazon Bedrock in SageMaker Unified Studio. Make sure to **Topics** + [ ## Prerequisites for deploying an exported app ](#app-deploy-app-prerequisites) + [ ## Deploy the exported app ](#app-deploy-app-deploy) ## Prerequisites for deploying an exported app Before you can deploy a chat agent app that you have exported, you must first do the following: **To prepare for app deployment** 1. Install the latest version of the AWS CLI on your local machine by following the instructions at [Install or update to the latest version of the AWS CLI](https://docs.aws.amazon.com/cli/latest/userguide/getting-started-install.html). 1. Set up AWS credentials for the AWS CLI on your local machine by following the instructions at [Configure the AWS CLI](https://docs.aws.amazon.com/cli/latest/userguide/cli-chap-configure.html). The credentials that the deployment script uses will follow the [order of precedence](https://docs.aws.amazon.com/cli/latest/userguide/cli-chap-configure.html#configure-precedence). 1. (Optional) Using the AWS account that you set up in step 2, create an AWS KMS key for app export by following the instructions at [Creating keys](https://docs.aws.amazon.com/kms/latest/developerguide/create-keys.html). The key must be tagged with key `EnableBedrock` and a value of `true`. The key must also have a key policy that allows it to be used for encryption of your chat agent app resources. You may use the suggested policy declared in the `kms-key-policy.json` file of your zip package. 1. Create an Amazon S3 bucket to hold the app files that you export by following the instructions at [Creating a bucket](https://docs.aws.amazon.com/AmazonS3/latest/userguide/create-bucket-overview.html). Make sure the bucket is in the same AWS Region as the app that you are deploying. 1. Create an IAM role that includes the policies from `provisioning-inline-policy.json`. For information about creating a role, see [IAM role creation](https://docs.aws.amazon.com/IAM/latest/UserGuide/id_roles_create.html). 1. If your app includes a Knowledge Base, copy the data source file to a folder named `data/` in the Amazon S3 bucket that you created in step 4. If your app uses a document as a datasource, you supply a list of datasource files to the deployment script. For more information, see [Deploy the exported app](#app-deploy-app-deploy). 1. If your app calls a function that requires authorization, update the function environment secret in Amazon SageMaker AI to the authorization method that your function uses. Run the following command: ``` aws secretsmanager update-secret \ --secret-id br-studio/function-name-export-environment-id \ --secret-string 'secret-value' ``` To get the `function-name` and `export-environment-id` values, open the *amazon-bedrock-ide-app-stack-*nnnn*.json* file from the files that you exported in [Export your Amazon Bedrock app](app-export-chat-app.md). The values are in the `FunctionsStack0` JSON object. Replace the following values: + `function-name` — to the value of the `functionName` field in the `FunctionsStack0` JSON object. + `export-environment-id` — to the value of the `exportAppInstanceId` field in the `FunctionsStack0` JSON object. + `secret-value` — to the intended value to be used for authentication. You specified the authentication type when you [created the function component](creating-a-function-component.md). Use the authentication values that you specified to complete the `secret-value`. If the function requires API Keys, the syntax of `secret-value` should be: `{"key-name-1":"key-value-1","key-name-2":"key-value-2"}` If the function requires Basic authentication, the syntax of `secret-value` should be: `{"___AuthType___":"BASIC", "username":"username-value", "password":"password-value"}` If the function requires Bearer token authentication, the syntax of `secret-value` should be: `{"___AuthType___":"BEARER", "tokenValue":"token-value"}` 1. Next step: [Deploy the exported app](#app-deploy-app-deploy). ## Deploy the exported app Before deploying your chat agent app, be sure to do the [prerequisite steps](#app-deploy-app-prerequisites). Deploying a chat agent app deploys the AWS infrastructure files that you need to run the app in AWS. **To deploy an exported app** 1. At the command prompt, do the following: 1. Navigate to the zip file that you exported from Amazon Bedrock in SageMaker Unified Studio. 1. Assume the role of the AWS that you created in step 3 of [Prerequisites for deploying an exported app](#app-deploy-app-prerequisites). 1. Use the following command to make sure the deployment script (`deployApp.sh`) is executable: ``` chmod +x deployApp.sh ``` 1. Run the deployment script with the following command: ``` ./deployApp.sh \ [--awsRegion=value] \ [--s3BucketName=value] \ [--assetsS3Path=value] \ [--kmsKeyArn=value] \ [--dataFiles=value] ``` Replace the following values: + `awsRegion` — with the AWS Region that you want to deploy the app to. Amazon Bedrock must be available in the Region you use. For more information, see [Supported AWS Regions](https://docs.aws.amazon.com/bedrock/latest/userguide/bedrock-regions.html). + `s3BucketName` — With the Amazon S3 bucket that you created in step 5 of [Prerequisites for deploying an exported app](#app-deploy-app-prerequisites). The deployment store the CFN templates and application data files in this bucket. + `assetsS3Path` — (Optional) With the path in `s3BucketName` that you want deployment to store application files to. + `kmsKeyArn` — (Optional) with the ARN of the KMS Key that you created in step 3 of [Prerequisites for deploying an exported app](#app-deploy-app-prerequisites). + `dataFiles` — With a comma-separated list of data source file paths. Required for apps that use a document data source. For example, if you have a chat agent app with a single document as a data source, and you want to deploy the app with encryption, you can use the following command. ``` ./deployApp.sh \ --awsRegion=us-east-1 \ --s3BucketName=my-s3-bucket-name-for-exported-chat-apps \ --assetsS3Path=my-prod-folder/my-chat-app \ --kmsKeyArn=arn:aws:kms:us-east-1:111122223333:key/11111111-2222-3333-4444-555555555555 \ --dataFiles=my-data-source.pdf ``` 1. (Optional) Monitor the deployment in the AWS CloudFormation console. 1. Note the output from the script. You need it to run the chat agent app. It should be similar to: `node amazon-bedrock-ide-app.mjs --question="prompt" --region="AWS Region"`. When you run the app, specify the following parameters: + `question` – The prompt that you want to start the app with. + `region` – The AWS Region that you deployed the app to. Use the value of `awsRegion` that you specified in step 1c. For example, `node amazon-bedrock-ide-app.mjs --question="Tell me about my documents" --region="us-east-1"` 1. Next step: [Run a deployed Amazon Bedrock app](app-run-app.md). # Run a deployed Amazon Bedrock app Run a deployed app The following instructions show you the steps you take to run a deployed Amazon Bedrock in SageMaker Unified Studio chat agent app. **Topics** + [ ## Prerequisites for running a chat agent app ](#app-run-app-prerequisites) + [ ## Run the app ](#app-deploy-app-run) ## Prerequisites for running a chat agent app Before you can run an app that you have exported, you must first do the following: **To prepare for running an app** 1. Download and install Node.js. For more information, see [Download Node.js](https://nodejs.org/en/download/package-manager). 1. At the command prompt, install third-party Node.js libraries by running the following commands: ``` npm install minimist npm install aws-sdk npm install @aws-sdk/credential-providers npm install @aws-sdk/client-bedrock-agent-runtime npm install @aws-sdk/client-bedrock-runtime ``` For a flow app you also need the following ``` npm install @aws-sdk/client-bedrock-agent ``` 1. Create or update an IAM role in which you want to run the app. For the policy, use the policy created by `deployApp.sh` when you exported the app. The policy name is `BRStudioExportedAppInvocationRolePolicy-exportProjectId`. The policy is declared in invocation-policy-\$1.json. For more information, see [Creating roles](https://docs.aws.amazon.com/IAM/latest/UserGuide/id_roles_create.html). ## Run the app To run your app, you need an IAM role with with permissions to invoke Amazon Bedrock resources. When you deploy the app, the CloudFormation stack deployed through `deployApp.sh` script provisions a suitable policy in your AWS account (declared in `invocation-policy-*.json`). **To run the app** 1. Switch to the IAM role that you created in step 3 of [Prerequisites for running a chat agent app](#app-run-app-prerequisites). 1. Run the app by entering the command you noted in step 3 of [Deploy the exported app](app-deploy-app.md#app-deploy-app-deploy).