> For clean Markdown of any page, append .md to the page URL.
> For a complete documentation index, see https://respan.ai/docs/llms.txt.
> For AI client integration (Claude Code, Cursor, etc.), connect to the MCP server at https://respan.ai/_mcp/server.

# AWS Bedrock (tracing)

> Trace Amazon Bedrock calls with Respan in Python or TypeScript.

[Amazon Bedrock](https://docs.aws.amazon.com/bedrock/) is a fully managed service that offers foundation models from leading AI providers through a single API. Respan gives you full observability over Bedrock invocations, streamed responses, and tool calls, plus separate gateway routing through the OpenAI-compatible Respan endpoint.

#### Set up Respan

Create an account at [platform.respan.ai](https://platform.respan.ai) and grab an [API key](https://platform.respan.ai/platform/api/api-keys).

Run `npx @respan/cli setup` to set up with your coding agent.

#### Use Respan Gateway

See [Amazon Bedrock gateway setup](/docs/gateway/aws-bedrock) to route Bedrock model calls through the Respan gateway.

#### Example projects

* [TypeScript examples](https://github.com/respanai/respan-example-projects/tree/main/typescript/tracing/aws-bedrock)
* [Example projects root](https://github.com/respanai/respan-example-projects)

## Setup

#### Install packages

```bash Python
pip install respan-ai respan-instrumentation-aws-bedrock boto3
```

```bash TypeScript
npm install @respan/respan @respan/tracing @respan/instrumentation-aws-bedrock @aws-sdk/client-bedrock-runtime dotenv
```

#### Set environment variables

```bash
export AWS_ACCESS_KEY_ID="YOUR_AWS_ACCESS_KEY_ID"
export AWS_SECRET_ACCESS_KEY="YOUR_AWS_SECRET_ACCESS_KEY"
export AWS_REGION="us-east-1"
export RESPAN_API_KEY="YOUR_RESPAN_API_KEY"
```

AWS credentials are used for direct Bedrock requests. `RESPAN_API_KEY` is used to export traces to Respan.

#### Initialize and run

```python Python
import json
import boto3
from respan import Respan
from respan_instrumentation_aws_bedrock import AWSBedrockInstrumentor

respan = Respan(instrumentations=[AWSBedrockInstrumentor()])

client = boto3.client("bedrock-runtime", region_name="us-east-1")

response = client.invoke_model(
    modelId="anthropic.claude-3-sonnet-20240229-v1:0",
    body=json.dumps({
        "anthropic_version": "bedrock-2023-05-31",
        "max_tokens": 1024,
        "messages": [{"role": "user", "content": "Say hello in three languages."}],
    }),
    contentType="application/json",
)
result = json.loads(response["body"].read())
print(result["content"][0]["text"])
```

```typescript TypeScript
import "dotenv/config";
import {
  BedrockRuntimeClient,
  ConverseCommand,
} from "@aws-sdk/client-bedrock-runtime";
import { Respan } from "@respan/respan";
import { AWSBedrockInstrumentor } from "@respan/instrumentation-aws-bedrock";

const respan = new Respan({
  apiKey: process.env.RESPAN_API_KEY,
  baseURL: process.env.RESPAN_BASE_URL,
  instrumentations: [new AWSBedrockInstrumentor()],
});
await respan.initialize();

const bedrock = new BedrockRuntimeClient({ region: process.env.AWS_REGION ?? "us-east-1" });

try {
  const response = await respan.withWorkflow({ name: "aws_bedrock.converse.workflow" }, async () => {
    return bedrock.send(
      new ConverseCommand({
        modelId: process.env.BEDROCK_MODEL_ID ?? "anthropic.claude-3-haiku-20240307-v1:0",
        system: [{ text: "Answer with one concise sentence." }],
        messages: [
          {
            role: "user",
            content: [{ text: "What does the Bedrock Converse API do?" }],
          },
        ],
      })
    );
  });
  console.log(response.output?.message?.content?.[0]?.text ?? "");
} finally {
  await respan.shutdown();
}
```

#### View your trace

Open the [Traces page](https://platform.respan.ai/platform/traces) to see your auto-instrumented LLM spans.

## Configuration

| Parameter             | Type                  | Default     | Description                                                                                                |
| --------------------- | --------------------- | ----------- | ---------------------------------------------------------------------------------------------------------- |
| `api_key`             | `str \| None`         | `None`      | Falls back to `RESPAN_API_KEY` env var.                                                                    |
| `base_url`            | `str \| None`         | `None`      | Falls back to `RESPAN_BASE_URL` env var.                                                                   |
| `instrumentations`    | `list`                | `[]`        | Plugin instrumentations to activate, such as `AWSBedrockInstrumentor()` or `new AWSBedrockInstrumentor()`. |
| `sdkModule`           | `object \| undefined` | `undefined` | TypeScript only. Optional AWS SDK module instance for runtimes that resolve multiple copies.               |
| `customer_identifier` | `str \| None`         | `None`      | Default customer identifier for all spans.                                                                 |
| `metadata`            | `dict \| None`        | `None`      | Default metadata attached to all spans.                                                                    |
| `environment`         | `str \| None`         | `None`      | Environment tag, such as `"production"`.                                                                   |

## Supported calls

| SDK call                        | Traced                                                        |
| ------------------------------- | ------------------------------------------------------------- |
| `InvokeModel`                   | Model invocation spans                                        |
| `InvokeModelWithResponseStream` | Streaming invocation spans after the stream is consumed       |
| `Converse`                      | Chat spans with messages, output, usage, and tool definitions |
| `ConverseStream`                | Streaming chat spans after the stream is consumed             |

## Attributes

### In Respan()

Set defaults at initialization. These apply to all spans.

```python Python
from respan import Respan
from respan_instrumentation_aws_bedrock import AWSBedrockInstrumentor

respan = Respan(
    instrumentations=[AWSBedrockInstrumentor()],
    customer_identifier="user_123",
    metadata={"service": "chat-api", "version": "1.0.0"},
)
```

```typescript TypeScript
import { Respan } from "@respan/respan";
import { AWSBedrockInstrumentor } from "@respan/instrumentation-aws-bedrock";

const respan = new Respan({
  instrumentations: [new AWSBedrockInstrumentor()],
});
```

### With propagate\_attributes

Override per-request using a context scope.

```python Python
import json
from respan import Respan, propagate_attributes
from respan_instrumentation_aws_bedrock import AWSBedrockInstrumentor

respan = Respan(instrumentations=[AWSBedrockInstrumentor()])

def handle_request(user_id: str, question: str):
    with propagate_attributes(
        customer_identifier=user_id,
        thread_identifier="conv_abc_123",
        metadata={"plan": "pro"},
    ):
        response = client.invoke_model(
            modelId="anthropic.claude-3-sonnet-20240229-v1:0",
            body=json.dumps({
                "anthropic_version": "bedrock-2023-05-31",
                "max_tokens": 1024,
                "messages": [{"role": "user", "content": question}],
            }),
            contentType="application/json",
        )
        result = json.loads(response["body"].read())
        print(result["content"][0]["text"])
```

```typescript TypeScript
async function handleRequest(userId: string, question: string) {
  await respan.propagateAttributes(
    {
      customer_identifier: userId,
      thread_identifier: "conv_abc_123",
      metadata: { plan: "pro" },
    },
    async () => {
      const response = await bedrock.send(
        new ConverseCommand({
          modelId: "anthropic.claude-3-haiku-20240307-v1:0",
          messages: [{ role: "user", content: [{ text: question }] }],
        })
      );
      console.log(response.output?.message?.content?.[0]?.text ?? "");
    }
  );
}
```

| Attribute             | Type   | Description                                           |
| --------------------- | ------ | ----------------------------------------------------- |
| `customer_identifier` | `str`  | Identifies the end user in Respan analytics.          |
| `thread_identifier`   | `str`  | Groups related messages into a conversation.          |
| `metadata`            | `dict` | Custom key-value pairs. Merged with default metadata. |