> ## Documentation Index
> Fetch the complete documentation index at: https://docs.pipecat.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# AWS Bedrock

> Large Language Model service implementation using Amazon Bedrock API

## Overview

`AWSBedrockLLMService` provides access to Amazon's foundation models including Anthropic Claude and Amazon Nova, with streaming responses, function calling, and multimodal capabilities through Amazon's managed AI service for enterprise-grade LLM deployment.

<CardGroup cols={2}>
  <Card title="AWS Bedrock LLM API Reference" icon="code" href="https://reference-server.pipecat.ai/en/latest/api/pipecat.services.aws.llm.html">
    Pipecat's API methods for AWS Bedrock integration
  </Card>

  <Card title="Example Implementation" icon="play" href="https://github.com/pipecat-ai/pipecat/blob/main/examples/function-calling/function-calling-aws.py">
    Complete example with function calling
  </Card>

  <Card title="AWS Bedrock Documentation" icon="book" href="https://docs.aws.amazon.com/bedrock/latest/userguide/what-is-bedrock.html">
    Official AWS Bedrock documentation and features
  </Card>

  <Card title="AWS Console" icon="microphone" href="https://console.aws.amazon.com/bedrock/">
    Access foundation models and manage IAM
  </Card>
</CardGroup>

## Installation

To use AWS Bedrock services, install the required dependencies:

```bash theme={null}
uv add "pipecat-ai[aws]"
```

## Prerequisites

### AWS Account Setup

Before using AWS Bedrock LLM services, you need:

1. **AWS Account**: Sign up at [AWS Console](https://console.aws.amazon.com/)
2. **IAM User**: Create an IAM user with Amazon Bedrock permissions
3. **Model Access**: Request access to foundation models in your AWS region
4. **Credentials**: Set up AWS access keys and region configuration

### Required Environment Variables

* `AWS_ACCESS_KEY_ID`: Your AWS access key ID
* `AWS_SECRET_ACCESS_KEY`: Your AWS secret access key
* `AWS_SESSION_TOKEN`: Session token (if using temporary credentials)
* `AWS_REGION`: AWS region (defaults to "us-east-1")

## Configuration

<ParamField path="model" type="str" default="None" deprecated>
  AWS Bedrock model identifier (e.g.,
  `"us.anthropic.claude-sonnet-4-5-20250929-v1:0"`,
  `"us.amazon.nova-pro-v1:0"`). *Deprecated in v0.0.105. Use
  `settings=AWSBedrockLLMService.Settings(...)` instead.*
</ParamField>

<ParamField path="aws_access_key" type="str" default="None">
  AWS access key ID. If `None`, uses the `AWS_ACCESS_KEY_ID` environment
  variable or default credential chain.
</ParamField>

<ParamField path="aws_secret_key" type="str" default="None">
  AWS secret access key. If `None`, uses the `AWS_SECRET_ACCESS_KEY` environment
  variable or default credential chain.
</ParamField>

<ParamField path="aws_session_token" type="str" default="None">
  AWS session token for temporary credentials. If `None`, uses the
  `AWS_SESSION_TOKEN` environment variable.
</ParamField>

<ParamField path="aws_region" type="str" default="None">
  AWS region for the Bedrock service. If `None`, uses the `AWS_REGION`
  environment variable, defaulting to `"us-east-1"`.
</ParamField>

<ParamField path="settings" type="AWSBedrockLLMService.Settings" default="None">
  Runtime-configurable model settings. See [Settings](#settings) below.
</ParamField>

<ParamField path="params" type="InputParams" default="None" deprecated>
  Runtime-configurable model settings. See [Settings](#settings) below.
  *Deprecated in v0.0.105. Use `settings=AWSBedrockLLMService.Settings(...)`
  instead.*
</ParamField>

<ParamField path="stop_sequences" type="List[str]" default="None" deprecated>
  List of strings that stop generation when encountered. *Deprecated in
  v0.0.105. Use `settings=AWSBedrockLLMService.Settings(stop_sequences=...)`
  instead.*
</ParamField>

<ParamField path="client_config" type="botocore.config.Config" default="None">
  Custom boto3 client configuration. If `None`, uses defaults with 5-minute
  connect/read timeouts and 3 retry attempts.
</ParamField>

<ParamField path="retry_timeout_secs" type="float" default="5.0">
  Request timeout in seconds. Used when `retry_on_timeout` is enabled to
  determine when to retry.
</ParamField>

<ParamField path="retry_on_timeout" type="bool" default="False">
  Whether to retry the request once if it times out. The retry attempt has no
  timeout limit.
</ParamField>

### Settings

Runtime-configurable settings passed via the `settings` constructor argument using `AWSBedrockLLMService.Settings(...)`. These can be updated mid-conversation with `LLMUpdateSettingsFrame`. See [Service Settings](/pipecat/fundamentals/service-settings) for details.

| Parameter                         | Type        | Default     | Description                                                                                                                                                                                                                                                |
| --------------------------------- | ----------- | ----------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `model`                           | `str`       | `None`      | AWS Bedrock model identifier. *(Inherited from base settings.)*                                                                                                                                                                                            |
| `system_instruction`              | `str`       | `None`      | System instruction/prompt for the model. *(Inherited from base settings.)*                                                                                                                                                                                 |
| `max_tokens`                      | `int`       | `NOT_GIVEN` | Maximum number of tokens to generate.                                                                                                                                                                                                                      |
| `temperature`                     | `float`     | `NOT_GIVEN` | Sampling temperature (0.0 to 1.0). Lower values are more focused, higher values are more creative.                                                                                                                                                         |
| `top_p`                           | `float`     | `NOT_GIVEN` | Top-p (nucleus) sampling (0.0 to 1.0). Controls diversity of output.                                                                                                                                                                                       |
| `top_k`                           | `int`       | `NOT_GIVEN` | Top-k sampling parameter.                                                                                                                                                                                                                                  |
| `seed`                            | `int`       | `NOT_GIVEN` | Random seed for deterministic outputs.                                                                                                                                                                                                                     |
| `stop_sequences`                  | `List[str]` | `NOT_GIVEN` | List of strings that stop generation when encountered.                                                                                                                                                                                                     |
| `latency`                         | `str`       | `NOT_GIVEN` | Performance mode: `"standard"` or `"optimized"`.                                                                                                                                                                                                           |
| `enable_prompt_caching`           | `bool`      | `NOT_GIVEN` | Whether to enable prompt caching by adding cachePoint markers to system prompts and tool definitions. Can reduce TTFT by up to 85% for multi-turn conversations. See [AWS docs](https://docs.aws.amazon.com/bedrock/latest/userguide/prompt-caching.html). |
| `additional_model_request_fields` | `dict`      | `NOT_GIVEN` | Additional model-specific parameters passed directly to the API.                                                                                                                                                                                           |

<Note>
  `NOT_GIVEN` values are omitted from the inference config, letting the Bedrock
  API use its own defaults. Only parameters that are explicitly set are included
  in the request. This avoids conflicts with models that don't allow certain
  parameter combinations (e.g., `temperature` and `top_p` together).
</Note>

## Usage

### Basic Setup

```python theme={null}
from pipecat.services.aws import AWSBedrockLLMService

llm = AWSBedrockLLMService(
    model="us.anthropic.claude-sonnet-4-5-20250929-v1:0",
    aws_access_key=os.getenv("AWS_ACCESS_KEY_ID"),
    aws_secret_key=os.getenv("AWS_SECRET_ACCESS_KEY"),
    aws_region=os.getenv("AWS_REGION", "us-east-1"),
)
```

### With Custom Settings

```python theme={null}
from pipecat.services.aws import AWSBedrockLLMService

llm = AWSBedrockLLMService(
    model="us.amazon.nova-pro-v1:0",
    aws_access_key=os.getenv("AWS_ACCESS_KEY_ID"),
    aws_secret_key=os.getenv("AWS_SECRET_ACCESS_KEY"),
    aws_region="us-east-1",
    settings=AWSBedrockLLMService.Settings(
        max_tokens=2048,
        temperature=0.7,
        latency="optimized",
    ),
)
```

### Updating Settings at Runtime

Model settings can be changed mid-conversation using `LLMUpdateSettingsFrame`:

```python theme={null}
from pipecat.frames.frames import LLMUpdateSettingsFrame
from pipecat.services.aws.llm import AWSBedrockLLMSettings

await task.queue_frame(
    LLMUpdateSettingsFrame(
        delta=AWSBedrockLLMSettings(
            temperature=0.3,
            max_tokens=1024,
        )
    )
)
```

<Tip>
  The `InputParams` / `params=` pattern is deprecated as of v0.0.105. Use
  `Settings` / `settings=` instead. See the [Service Settings
  guide](/pipecat/fundamentals/service-settings) for migration details.
</Tip>

## Notes

* **Credential chain**: If `aws_access_key` and `aws_secret_key` are not provided, the service falls back to environment variables and then the standard AWS credential chain (IAM roles, instance profiles, etc.).
* **No-op tool handling**: AWS Bedrock requires at least one tool to be defined when tool content exists in the conversation. The service automatically adds a placeholder tool when needed to prevent API errors.
* **Model-specific parameters**: Some models (e.g., Claude Sonnet 4.5) don't allow certain parameter combinations. The service only includes explicitly set parameters in the inference config to avoid conflicts.
* **Retry behavior**: When `retry_on_timeout=True`, the first attempt uses the `retry_timeout_secs` timeout. If it times out, a second attempt is made with no timeout limit.
* **System instruction precedence**: If both `system_instruction` (from the constructor) and a system message in the context are set, the constructor's `system_instruction` takes precedence and a warning is logged.

## Event Handlers

`AWSBedrockLLMService` supports the following event handlers, inherited from [LLMService](/api-reference/server/events/service-events):

| Event                       | Description                                                             |
| --------------------------- | ----------------------------------------------------------------------- |
| `on_completion_timeout`     | Called when an LLM completion request times out                         |
| `on_function_calls_started` | Called when function calls are received and execution is about to start |

```python theme={null}
@llm.event_handler("on_completion_timeout")
async def on_completion_timeout(service):
    print("LLM completion timed out")
```