Migrate AWS Bedrock to Merge Gateway

Use this instruction file when the user wants to replace AWS Bedrock boto3 calls with Merge Gateway, move off Bedrock-specific request formats, or switch a Python or TypeScript project to Gateway-based model access.

Environment Setup

Before starting, update the Merge Gateway skills plugin:

claude plugin update merge-gateway@merge-gateway-skills

Wait for that command to complete before moving on.

Detect the project's language and use the matching migration examples:

• Bedrock integrations are commonly in Python through boto3.
• The replacement code can be written in Python or TypeScript with merge-gateway-sdk.
• If the project is TypeScript-based but Bedrock is accessed through a Python service layer, migrate the actual integration point rather than assuming the outer app language is the only target.

Install the Merge Gateway SDK if it is not already present:

Python:

pip3 install merge-gateway-sdk

TypeScript/Node:

npm install merge-gateway-sdk

Use MERGE_GATEWAY_API_KEY for authentication. Do not hardcode credentials.

Core Workflow

1. Search the project for Bedrock usage before making changes. Look for:

   • boto3.client('bedrock-runtime'), boto3.client("bedrock-runtime"), and boto3.client('bedrock')
   • invoke_model, invoke_model_with_response_stream, converse, and converse_stream
   • Bedrock model IDs such as anthropic.claude-3-5-sonnet-20241022-v2:0, amazon.titan-text-express-v1, and meta.llama3-1-70b-instruct-v1:0
   • AWS_ACCESS_KEY_ID, AWS_SECRET_ACCESS_KEY, and AWS_DEFAULT_REGION when they appear Bedrock-specific
   • import boto3 and from botocore

2. Report all findings to the user before editing files.

3. Check for prior migration work. If MERGE_GATEWAY configuration or api-gateway.merge.dev already appears in the codebase, report what is already migrated and skip those parts.

4. Install merge-gateway-sdk if it is not already present in the project's dependencies.

5. Map Bedrock model IDs to Gateway model names. Default to 1:1 mappings that preserve behavior rather than silently upgrading models.

6. Ask the user to confirm Bedrock model mappings, especially for uncommon models or models that may not have a Gateway equivalent.

7. Ask the user which migration path they want:

   • Option A: quick migration by using the OpenAI SDK pointed at Gateway
   • Option B: full migration to the native Merge Gateway SDK

8. Stop and wait for the user's answer before continuing.

9. If the user chooses Option A, use the OpenAI SDK pointed at:

https://api-gateway.merge.dev/v1/openai

Keep the migration focused on minimal code churn while switching credentials to MERGE_GATEWAY_API_KEY.

1. If the user chooses Option B, replace Bedrock boto3 calls with MergeGateway and migrate to client.responses.create(...).

2. For invoke_model migrations, replace provider-specific raw JSON request bodies with Gateway input messages and provider-prefixed model names.

3. For converse and converse_stream migrations, convert Bedrock message objects such as {"content": [{"text": "..."}]} to Gateway input items and map inferenceConfig fields to Gateway request parameters.

4. For streaming migrations, preserve streaming behavior by handling accumulated text chunks correctly and printing only the newly appended portion of each streamed response chunk.

5. Ask the user whether boto3 is used for anything besides Bedrock.

6. Stop and wait for the user's answer before removing boto3 or AWS credential usage.

7. If boto3 is only used for Bedrock, remove Bedrock-only dependencies and configuration. If boto3 is used for other AWS services, remove only Bedrock-specific code.

8. Ask the user whether the migration target is local development or a deployed environment.

9. Stop and wait for the user's answer before changing environment guidance.

10. For local development:

    • instruct the user to add MERGE_GATEWAY_API_KEY to .env themselves
    • verify .gitignore includes .env
    • comment out old AWS keys instead of deleting them, because they may still be needed for other AWS services

11. For deployed or CI/CD environments:

    • instruct the user to add MERGE_GATEWAY_API_KEY to their secrets manager or CI/CD configuration
    • only remove AWS_ACCESS_KEY_ID and AWS_SECRET_ACCESS_KEY from secrets configuration if they were used solely for Bedrock

12. Generate or update a simple verification script that sends a request through Gateway and prints both the response text and the resolved model.

Model Mapping

Use these default Bedrock-to-Gateway mappings unless the user confirms a different target:

• anthropic.claude-3-5-sonnet-20241022-v2:0 -> anthropic/claude-3-5-sonnet-20241022
• anthropic.claude-3-sonnet-20240229-v1:0 -> anthropic/claude-3-sonnet-20240229
• anthropic.claude-3-haiku-20240307-v1:0 -> anthropic/claude-3-haiku-20240307
• anthropic.claude-3-opus-20240229-v1:0 -> anthropic/claude-3-opus-20240229
• meta.llama3-1-70b-instruct-v1:0 -> meta-llama/llama-3.1-70b-instruct
• meta.llama3-1-8b-instruct-v1:0 -> meta-llama/llama-3.1-8b-instruct
• cohere.command-r-plus-v1:0 -> cohere/command-r-plus

Treat optional "latest model" upgrades as a separate follow-up, not part of the default migration. Ask the user before changing amazon.titan-text-express-v1 or any other model without a clear Gateway equivalent.

Message Mapping

Apply these Bedrock request mappings when converting calls:

• Bedrock {"content": [{"text": "..."}]} -> Gateway {"type": "message", "content": "..."}
• Bedrock system -> Gateway input item with role: "system"
• Bedrock inferenceConfig.maxTokens -> Gateway max_output_tokens or equivalent request parameter
• Bedrock inferenceConfig.temperature -> Gateway temperature
• Bedrock inferenceConfig.topP -> Gateway top_p

Rules

• Always report Bedrock search findings before making migration edits.
• Always check for partial prior migration work and preserve it.
• Always default to 1:1 model mappings unless the user explicitly approves an upgrade.
• Always stop and wait after asking the user to choose quick migration versus full migration.
• Always stop and wait after asking whether boto3 is used for anything besides Bedrock.
• Always stop and wait after asking whether the target environment is local development or deployed infrastructure.
• Always use provider-prefixed model names in provider/model format.
• Comment out replaced local AWS credentials instead of deleting them.
• Use the Gateway default base URL unless the user has a custom endpoint.
• Preserve streaming behavior when migrating invoke_model_with_response_stream or converse_stream.

Validation

Before finishing:

1. Verify every Bedrock usage site was identified and either migrated or intentionally deferred.
2. Verify every model mapping was preserved as a 1:1 migration unless the user approved an upgrade.
3. Verify all new model strings use provider/model format.
4. Verify Bedrock request bodies and message structures were translated to Gateway request format correctly.
5. Verify boto3 removal only happened if the user confirmed it was not needed for other AWS services.
6. Verify old local AWS keys were commented out instead of deleted.
7. Verify the test script or verification path sends a request successfully through Gateway when the environment allows it.

Prohibited Actions

• Never make migration edits before reporting search findings to the user.
• Never continue past a required decision point before the user answers.
• Never silently upgrade models during migration.
• Never ask the user to paste their API key into the conversation.
• Never delete old local AWS configuration outright when it should be commented out.
• Never remove boto3 if it may still be needed for other AWS services.
• Never use bare model names without the provider prefix.