> ## Documentation Index
> Fetch the complete documentation index at: https://allhandsai-dv-agent-canvas-release-notes.mintlify.site/llms.txt
> Use this file to discover all available pages before exploring further.

# AWS Bedrock

> OpenHands uses LiteLLM to make calls to AWS Bedrock models. You can find their documentation on using Bedrock as a provider [here](https://docs.litellm.ai/docs/providers/bedrock).

## AWS Bedrock Configuration

AWS Bedrock provides access to foundation models from Amazon and third-party providers like Anthropic Claude, Meta Llama, and Mistral.

### Prerequisites

1. An AWS account with Bedrock access enabled
2. IAM credentials with permissions to invoke Bedrock models
3. The desired models enabled in your AWS Bedrock console

### Environment Variables

When running Agent Canvas with the [official Docker image](/openhands/usage/agent-canvas/backend-setup/docker), add these options to the documented `docker run` command:

```bash theme={null}
--env LLM_AWS_ACCESS_KEY_ID="your-access-key-id" \
--env LLM_AWS_SECRET_ACCESS_KEY="your-secret-access-key" \
--env LLM_AWS_REGION_NAME="us-east-1"
```

The official `ghcr.io/openhands/agent-canvas:latest` image includes the AWS SDK for Python (`boto3`).

<Note>
  Make sure you have enabled the Bedrock models you want to use in the AWS Console. Go to **Amazon Bedrock** → **Model access** and request access to the models you need.
</Note>

### UI Configuration

In Agent Canvas:

1. Open `Settings > LLM` and enable the `Advanced` options.
2. Set `Custom Model` to the Bedrock model or inference profile ID. See [Model IDs](#model-ids).
3. Leave `Base URL` empty because Bedrock uses AWS endpoints automatically.
4. Leave `API Key` empty because authentication is handled through your AWS credentials.
5. Save the profile and start a new conversation to test it.

See [Manage LLM Profiles](/openhands/usage/agent-canvas/llm-profiles) for more information about profile settings.

### Model IDs

Bedrock model IDs are managed by AWS and may change over time. Use the exact **Model ID** from the AWS Console or the AWS documentation (no `bedrock/` prefix).

Example format:

* `Custom Model`: `anthropic.claude-3-5-sonnet-20241022-v2:0`

For a complete list of available models, see the [AWS Bedrock documentation](https://docs.aws.amazon.com/bedrock/latest/userguide/models-supported.html).

### Cross-Region Inference

Some models must be invoked through a cross-region inference profile rather than their direct foundation model ID. Inference profile IDs include a geographic prefix such as `us.`.

For example, use:

* `Custom Model`: `us.anthropic.claude-sonnet-4-5-20250929-v1:0`

instead of the direct model ID:

* `anthropic.claude-sonnet-4-5-20250929-v1:0`

No additional environment variables are required. Keep using the AWS region where you configured Bedrock access and your existing credentials. See [Increase throughput with cross-region inference](https://docs.aws.amazon.com/bedrock/latest/userguide/cross-region-inference.html) for supported profiles and regions.

### Using IAM Roles (Alternative to Access Keys)

If running OpenHands on AWS infrastructure such as EC2, ECS, or Lambda, you can use IAM roles instead of access keys:

1. Attach an IAM role with Bedrock permissions to your compute resource.
2. Omit the `LLM_AWS_ACCESS_KEY_ID` and `LLM_AWS_SECRET_ACCESS_KEY` environment variables.
3. The AWS SDK automatically uses the instance role credentials.

### Troubleshooting

#### "No module named 'boto3'" Error

If you encounter this error:

```text theme={null}
litellm.APIConnectionError: No module named 'boto3'
ModuleNotFoundError: No module named 'boto3'
```

First identify how you installed Agent Canvas:

* **Docker:** The current `ghcr.io/openhands/agent-canvas:latest` image includes `boto3`. Pull the latest image and recreate the container:

  ```bash theme={null}
  docker pull ghcr.io/openhands/agent-canvas:latest
  ```

* **npm or npx:** The Python environment managed by the npm distribution may not include the optional Bedrock dependency. Follow [OpenHands issue #16578](https://github.com/OpenHands/OpenHands/issues/16578) for the package fix. Use the official Agent Canvas Docker image if you need Bedrock while that issue remains open.

Do not install `boto3` into a temporary uv archive environment because Agent Canvas may recreate that environment.

#### On-Demand Throughput Is Not Supported

Some foundation model IDs cannot be invoked directly and return an error similar to:

```text theme={null}
Invocation of model ID ... with on-demand throughput isn't supported.
Retry your request with the ID or ARN of an inference profile that contains this model.
```

Use the corresponding inference profile ID or ARN, such as `us.anthropic.claude-sonnet-4-5-20250929-v1:0`. This error does not indicate a credential, model access, or `boto3` problem.

#### Access Denied Errors

If you receive access denied errors:

1. Verify your IAM credentials have the `bedrock:InvokeModel` permission
2. Check that the model is enabled in your AWS Bedrock console
3. Ensure you're using the correct AWS region where the model is available

#### Model Not Found

If the model is not found:

1. Verify the model ID is correct (check AWS documentation)
2. Ensure the model is enabled in your Bedrock model access settings
3. Check that the model is available in your selected AWS region