Amazon Bedrock Integration for Microsoft Agent Framework

1.0.0b260409 · active · verified Thu Apr 16

The `agent-framework-bedrock` library provides an integration for the Microsoft Agent Framework to connect with Amazon Bedrock. It enables Agent Framework applications to leverage Bedrock's foundational models for tasks such as Chat Completion, Text Generation, and Text Embeddings. This package is part of Microsoft's broader Agent Framework, which aims to provide a unified, open-source SDK for building, orchestrating, and deploying AI agents and multi-agent workflows in Python and .NET. The current version, `1.0.0b260409`, is a beta release, indicating active development within the recently released 1.0 version of the main `agent-framework`.

Common errors

```
botocore.exceptions.ClientError: An error occurred (AccessDeniedException) when calling the InvokeModel operation: User: arn:aws:iam::xxxxxxxxxxxx:user/your-user is not authorized to perform: bedrock:InvokeModel on resource: arn:aws:bedrock:us-east-1::foundation-model/anthropic.claude-v2 with an explicit deny in an identity-based policy
```
cause The AWS credentials used (either environment variables or configured profile) lack the necessary IAM permissions to invoke the specified Bedrock model in the given region.

fix Ensure the AWS IAM role or user associated with your credentials has an explicit `Allow` policy for `bedrock:InvokeModel` on the target Bedrock foundation model. Verify the region and model ARN are correct.
```
ValueError: Invalid Bedrock model_id 'invalid-model'. See https://docs.aws.amazon.com/bedrock/latest/userguide/models-supported.html
```
cause The `model` parameter passed to `BedrockChatClient` is not a valid Bedrock model ID or is not enabled for your AWS account/region.

fix Check the AWS Bedrock documentation for supported model IDs and ensure the model is enabled in your AWS account and the specified `region_name`. Update the `BEDROCK_MODEL_ID` environment variable or the `model` parameter accordingly.
```
ModuleNotFoundError: No module named 'agent_framework.amazon'
```
cause The `agent-framework-bedrock` package or the main `agent-framework` is not installed correctly, or the import path is wrong.

fix Ensure you have installed `agent-framework` (which includes connectors like `amazon`) or `agent-framework-bedrock` using `pip install agent-framework` or `pip install agent-framework-bedrock`. Verify the import statement is `from agent_framework.amazon import BedrockChatClient`.

Warnings

breaking As a beta package (`1.0.0b`), `agent-framework-bedrock` is subject to non-backward compatible changes. The underlying Microsoft Agent Framework itself has undergone breaking changes during its preview phase.
Fix: Refer to the latest Microsoft Agent Framework documentation and changelog, especially during upgrades, to identify and adapt to API changes. Pin exact versions for stability in production.
gotcha AWS IAM permissions are a common source of errors. The agent's execution role or your local credentials must have `bedrock:InvokeModel` and other necessary permissions (e.g., for `bedrock:InvokeAgentRuntime` if deploying agents).
Fix: Thoroughly review and configure your AWS IAM policies and roles. Ensure the principal calling Bedrock has the required `bedrock` permissions and that the chosen model is enabled in your AWS account and region. Check AWS documentation for specific permissions.
gotcha When interacting with Amazon Bedrock Agents (especially at a lower level or through `boto3`), the 'completion' field in the response is often an `EventStream` object, not a direct JSON object, which can lead to parsing errors.
Fix: If manually parsing responses, ensure you iterate over the `EventStream` to extract chunks and decode the content. The `BedrockChatClient` in `agent-framework` should handle this abstraction, but it's a known lower-level issue to be aware of.
gotcha There have been reports (e.g., GitHub issue #5165 for `microsoft/agent-framework`) where `BedrockChatClient` might send `toolConfig.toolChoice` without `toolConfig.tools` when an agent has no tools configured, causing AWS Bedrock API validation errors.
Fix: If encountering validation errors related to tool configuration when no tools are expected, check the `agent-framework` GitHub issues for patches or workarounds. This might require updating `agent-framework-bedrock` or the main `agent-framework` to a version where this specific bug is resolved.

Install

pip install agent-framework-bedrock Install specific package
pip install agent-framework Install main framework with all connectors (recommended for development)

Imports

BedrockChatClient
wrong:
```
from agent_framework_bedrock.services import BedrockChatClient
```
correct:
```
from agent_framework.amazon import BedrockChatClient
```
The `BedrockChatClient` is found under `agent_framework.amazon` within the main `agent-framework` package, not directly within `agent_framework_bedrock`.
Agent
```
from agent_framework import Agent
```
The core `Agent` class is imported directly from the `agent_framework` package.

Quickstart

This quickstart demonstrates how to initialize a `BedrockChatClient` and use it to create an `Agent` from the Microsoft Agent Framework. It assumes AWS credentials (AWS_ACCESS_KEY_ID, AWS_SECRET_ACCESS_KEY) and the AWS region (AWS_REGION_NAME) are configured in the environment, along with a specified Bedrock model ID (BEDROCK_MODEL_ID). The agent then processes a simple prompt and prints the response.

import asyncio
import os
from agent_framework import Agent
from agent_framework.amazon import BedrockChatClient
from agent_framework.core.message import Message

async def main():
    # Ensure AWS credentials (AWS_ACCESS_KEY_ID, AWS_SECRET_ACCESS_KEY)
    # and AWS_REGION_NAME are set as environment variables or via AWS CLI config.
    # Example Bedrock model ID, e.g., "anthropic.claude-v2" or "amazon.titan-text-express-v1"
    bedrock_model_id = os.environ.get("BEDROCK_MODEL_ID", "anthropic.claude-v2")
    aws_region = os.environ.get("AWS_REGION_NAME", "us-east-1")

    if not all(os.environ.get(var) for var in ["AWS_ACCESS_KEY_ID", "AWS_SECRET_ACCESS_KEY", "AWS_REGION_NAME"]):
        print("Warning: AWS credentials or region not fully configured via environment variables.")
        print("Please set AWS_ACCESS_KEY_ID, AWS_SECRET_ACCESS_KEY, and AWS_REGION_NAME.")
        # In a real application, you might raise an error or use a credential provider.

    try:
        # Initialize the Bedrock chat client
        client = BedrockChatClient(region_name=aws_region, model=bedrock_model_id)

        # Create an Agent Framework Agent with the Bedrock client
        bedrock_agent = Agent(
            client=client,
            instructions="You are a helpful AI assistant that responds concisely.",
            name="BedrockAssistant",
        )

        # Run a simple interaction
        response_messages = await bedrock_agent.run("Tell me a fun fact about Python.")

        # Print the agent's response
        for msg in response_messages:
            print(f"[{msg.author_name}]: {msg.text}")

    except Exception as e:
        print(f"An error occurred: {e}")
        print("Ensure AWS credentials and BEDROCK_MODEL_ID/AWS_REGION_NAME are correctly configured.")
        print("Also, verify that the specified Bedrock model is enabled in your AWS account and region.")

if __name__ == "__main__":
    asyncio.run(main())

view raw JSON →