Python: Bedrock agent (#10307)

### Motivation and Context

<!-- Thank you for your contribution to the semantic-kernel repo!
Please help reviewers and future users, providing the following
information:
  1. Why is this change required?
  2. What problem does it solve?
  3. What scenario does it contribute to?
  4. If it fixes an open issue, please link to the issue here.
-->
Address #10284

Integration of AWS Bedrock agent to SK Python

### Description
1. Implementation of Bedrock agent in SK (essentially an agent connector
to the Bedrock agent service).
2. A dedicated channel that works with Bedrock agents.
3. Samples on how to use Bedrock agents.

Unit and integration tests will be included in another PR to prevent
this PR from becoming too big.

<!-- Describe your changes, the overall approach, the underlying design.
These notes will help understanding how your code works. Thanks! -->

### Contribution Checklist

<!-- Before submitting this PR, please make sure: -->

- [x] The code builds clean without any errors or warnings
- [x] The PR follows the [SK Contribution
Guidelines](https://github.com/microsoft/semantic-kernel/blob/main/CONTRIBUTING.md)
and the [pre-submission formatting
script](https://github.com/microsoft/semantic-kernel/blob/main/CONTRIBUTING.md#development-scripts)
raises no violations
- [x] All unit tests pass, and I have added new tests where possible
- [x] I didn't break anyone 😄

python/pyproject.toml

@@ -60,8 +60,8 @@ chroma = [
     "chromadb >= 0.5,< 0.7"
 ]
 google = [
-    "google-cloud-aiplatform ~= 1.60",
-    "google-generativeai ~= 0.7"
+    "google-cloud-aiplatform == 1.60",
+    "google-generativeai == 0.7"
 ]
 hugging_face = [
     "transformers[torch] ~= 4.28",
@@ -116,7 +116,7 @@ pandas = [
     "pandas ~= 2.2"
 ]
 aws = [
-    "boto3>=1.28.57",
+    "boto3~=1.36.4",
 ]
 dapr = [
     "dapr>=1.14.0",

python/samples/concepts/README.md

@@ -17,6 +17,7 @@
 - [Mixed Chat Images](./agents/mixed_chat_images.py)
 - [Mixed Chat Reset](./agents/mixed_chat_reset.py)
 - [Mixed Chat Streaming](./agents/mixed_chat_streaming.py)
+- [Bedrock Agent](./agents/bedrock_agent/README.md)
 
 ### Audio - Using services that support audio-to-text and text-to-audio conversion
 

python/samples/concepts/agents/bedrock_agent/.env.example

@@ -0,0 +1,2 @@
+BEDROCK_AGENT_AGENT_RESOURCE_ROLE_ARN=[YOUR_AGENT_ROLE_AMAZON_RESOURCE_NAME]
+BEDROCK_AGENT_FOUNDATION_MODEL=[YOUR_FOUNDATION_MODEL]

python/samples/concepts/agents/bedrock_agent/README.md

@@ -0,0 +1,45 @@
+# Concept samples on how to use AWS Bedrock agents
+
+## Pre-requisites
+
+1. You need to have an AWS account and [access to the foundation models](https://docs.aws.amazon.com/bedrock/latest/userguide/model-access-permissions.html)
+2. [AWS CLI installed](https://docs.aws.amazon.com/cli/latest/userguide/getting-started-install.html) and [configured](https://boto3.amazonaws.com/v1/documentation/api/latest/guide/quickstart.html#configuration)
+
+## Samples
+
+| Sample | Description |
+|--------|-------------|
+| [bedrock_agent_simple_chat.py](bedrock_agent_simple_chat.py) | Demonstrates basic usage of the Bedrock agent. |
+| [bedrock_agent_simple_chat_streaming.py](bedrock_agent_simple_chat_streaming.py) | Demonstrates basic usage of the Bedrock agent with streaming. |
+| [bedrock_agent_with_kernel_function.py](bedrock_agent_with_kernel_function.py) | Shows how to use the Bedrock agent with a kernel function. |
+| [bedrock_agent_with_kernel_function_streaming.py](bedrock_agent_with_kernel_function_streaming.py) | Shows how to use the Bedrock agent with a kernel function with streaming. |
+| [bedrock_agent_with_code_interpreter.py](bedrock_agent_with_code_interpreter.py) | Example of using the Bedrock agent with a code interpreter. |
+| [bedrock_agent_with_code_interpreter_streaming.py](bedrock_agent_with_code_interpreter_streaming.py) | Example of using the Bedrock agent with a code interpreter and streaming. |
+| [bedrock_mixed_chat_agents.py](bedrock_mixed_chat_agents.py) | Example of using multiple chat agents in a single script. |
+| [bedrock_mixed_chat_agents_streaming.py](bedrock_mixed_chat_agents_streaming.py) | Example of using multiple chat agents in a single script with streaming. |
+| [bedrock_agent_update_agent.py](bedrock_agent_update_agent.py) | Example of updating an agent. |
+| [bedrock_agent_use_existing.py](bedrock_agent_use_existing.py) | Example of using an existing agent. |
+
+## Before running the samples
+
+You need to set up some environment variables to run the samples. Please refer to the [.env.example](.env.example) file for the required environment variables.
+
+### `BEDROCK_AGENT_AGENT_RESOURCE_ROLE_ARN`
+
+On your AWS console, go to the IAM service and go to **Roles**. Find the role you want to use and click on it. You will find the ARN in the summary section.
+
+### `BEDROCK_AGENT_FOUNDATION_MODEL`
+
+You need to make sure you have permission to access the foundation model. You can find the model ID in the [AWS documentation](https://docs.aws.amazon.com/bedrock/latest/userguide/models-supported.html). To see the models you have access to, find the policy attached to your role you should see a list of models you have access to under the `Resource` section.
+
+### How to add the `bedrock:InvokeModelWithResponseStream` action to an IAM policy
+
+1. Open the [IAM console](https://console.aws.amazon.com/iam/).
+2. On the left navigation pane, choose `Roles` under `Access management`.
+3. Find the role you want to edit and click on it.
+4. Under the `Permissions policies` tab, click on the policy you want to edit.
+5. Under the `Permissions defined in this policy` section, click on the service. You should see **Bedrock** if you already have access to the Bedrock agent service.
+6. Click on the service, and then click `Edit`.
+7. On the right, you will be able to add an action. Find the service and search for `InvokeModelWithResponseStream`.
+8. Check the box next to the action and then sroll all the way down and click `Next`.
+9. Follow the prompts to save the changes.

python/samples/concepts/agents/bedrock_agent/bedrock_agent_simple_chat.py

@@ -0,0 +1,52 @@
+# Copyright (c) Microsoft. All rights reserved.
+
+import asyncio
+
+from semantic_kernel.agents.bedrock.bedrock_agent import BedrockAgent
+
+# This sample shows how to interact with a Bedrock agent in the simplest way.
+# This sample uses the following main component(s):
+# - a Bedrock agent
+# You will learn how to create a new Bedrock agent and talk to it.
+
+AGENT_NAME = "semantic-kernel-bedrock-agent"
+INSTRUCTION = "You are a friendly assistant. You help people find information."
+
+
+async def main():
+    bedrock_agent = await BedrockAgent.create(AGENT_NAME, instructions=INSTRUCTION)
+    session_id = BedrockAgent.create_session_id()
+
+    try:
+        while True:
+            user_input = input("User:> ")
+            if user_input == "exit":
+                print("\n\nExiting chat...")
+                break
+
+            # Invoke the agent
+            # The chat history is maintained in the session
+            async for response in bedrock_agent.invoke(
+                session_id=session_id,
+                input_text=user_input,
+            ):
+                print(f"Bedrock agent: {response}")
+    except KeyboardInterrupt:
+        print("\n\nExiting chat...")
+        return False
+    except EOFError:
+        print("\n\nExiting chat...")
+        return False
+    finally:
+        # Delete the agent
+        await bedrock_agent.delete_agent()
+
+    # Sample output (using anthropic.claude-3-haiku-20240307-v1:0):
+    # User:> Hi, my name is John.
+    # Bedrock agent: Hello John. How can I help you?
+    # User:> What is my name?
+    # Bedrock agent: Your name is John.
+
+
+if __name__ == "__main__":
+    asyncio.run(main())

python/samples/concepts/agents/bedrock_agent/bedrock_agent_simple_chat_streaming.py

@@ -0,0 +1,54 @@
+# Copyright (c) Microsoft. All rights reserved.
+
+import asyncio
+
+from semantic_kernel.agents.bedrock.bedrock_agent import BedrockAgent
+
+# This sample shows how to interact with a Bedrock agent via streaming in the simplest way.
+# This sample uses the following main component(s):
+# - a Bedrock agent
+# You will learn how to create a new Bedrock agent and talk to it.
+
+AGENT_NAME = "semantic-kernel-bedrock-agent"
+INSTRUCTION = "You are a friendly assistant. You help people find information."
+
+
+async def main():
+    bedrock_agent = await BedrockAgent.create(AGENT_NAME, instructions=INSTRUCTION)
+    session_id = BedrockAgent.create_session_id()
+
+    try:
+        while True:
+            user_input = input("User:> ")
+            if user_input == "exit":
+                print("\n\nExiting chat...")
+                break
+
+            # Invoke the agent
+            # The chat history is maintained in the session
+            print("Bedrock agent: ", end="")
+            async for response in bedrock_agent.invoke_stream(
+                session_id=session_id,
+                input_text=user_input,
+            ):
+                print(response, end="")
+            print()
+    except KeyboardInterrupt:
+        print("\n\nExiting chat...")
+        return False
+    except EOFError:
+        print("\n\nExiting chat...")
+        return False
+    finally:
+        # Delete the agent
+        await bedrock_agent.delete_agent()
+
+    # Sample output (using anthropic.claude-3-haiku-20240307-v1:0):
+    # User:> Hi, my name is John.
+    # Bedrock agent: Hello John. How can I help you?
+    # User:> What is my name?
+    # Bedrock agent: Your name is John.
+
+
+if __name__ == "__main__":
+    asyncio.run(main())

python/samples/concepts/agents/bedrock_agent/bedrock_agent_update_agent.py

@@ -0,0 +1,55 @@
+# Copyright (c) Microsoft. All rights reserved.
+
+import asyncio
+
+from semantic_kernel.agents.bedrock.bedrock_agent import BedrockAgent
+
+# This sample shows how to update an existing Bedrock agent.
+# This sample uses the following main component(s):
+# - a Bedrock agent
+# You will learn how to connect to a Bedrock agent and update its properties.
+
+
+# Make sure to replace AGENT_NAME and AGENT_ID with the correct values
+AGENT_NAME = "semantic-kernel-bedrock-agent"
+INSTRUCTION = "You are a friendly assistant but you don't know anything about AI."
+NEW_INSTRUCTION = "You are a friendly assistant and you know a lot about AI."
+
+
+async def main():
+    bedrock_agent = await BedrockAgent.create(AGENT_NAME, instructions=INSTRUCTION)
+
+    async def ask_about_ai():
+        session_id = BedrockAgent.create_session_id()
+        async for response in bedrock_agent.invoke(
+            session_id=session_id,
+            input_text="What is AI in one sentence?",
+        ):
+            print(response)
+
+    try:
+        print("Before updating the agent:")
+        await ask_about_ai()
+
+        await bedrock_agent.update_agent(instruction=NEW_INSTRUCTION)
+
+        print("After updating the agent:")
+        await ask_about_ai()
+    finally:
+        # Delete the agent
+        await bedrock_agent.delete_agent()
+
+    # Sample output (using anthropic.claude-3-haiku-20240307-v1:0):
+    # Before updating the agent:
+    # I apologize, but I do not have any information about AI or the ability to define it.
+    # As I mentioned, I am a friendly assistant without any knowledge about AI. I cannot
+    # provide a definition for AI in one sentence. If you have a different question I can
+    # try to assist with, please let me know.
+    # After updating the agent:
+    # AI is the field of computer science that aims to create systems and machines that can
+    # perform tasks that typically require human intelligence, such as learning, problem-solving,
+    # perception, and decision-making.
+
+
+if __name__ == "__main__":
+    asyncio.run(main())

python/samples/concepts/agents/bedrock_agent/bedrock_agent_use_existing.py

@@ -0,0 +1,51 @@
+# Copyright (c) Microsoft. All rights reserved.
+
+import asyncio
+
+from semantic_kernel.agents.bedrock.bedrock_agent import BedrockAgent
+
+# This sample shows how to interact with a Bedrock agent in the simplest way.
+# This sample uses the following main component(s):
+# - a Bedrock agent that has already been created
+# You will learn how to connect to an existing Bedrock agent and talk to it.
+
+
+# Make sure to replace AGENT_NAME and AGENT_ID with the correct values
+AGENT_NAME = "semantic-kernel-bedrock-agent"
+AGENT_ID = "..."
+
+
+async def main():
+    bedrock_agent = await BedrockAgent.retrieve(AGENT_ID, AGENT_NAME)
+    session_id = BedrockAgent.create_session_id()
+
+    try:
+        while True:
+            user_input = input("User:> ")
+            if user_input == "exit":
+                print("\n\nExiting chat...")
+                break
+
+            # Invoke the agent
+            # The chat history is maintained in the session
+            async for response in bedrock_agent.invoke(
+                session_id=session_id,
+                input_text=user_input,
+            ):
+                print(f"Bedrock agent: {response}")
+    except KeyboardInterrupt:
+        print("\n\nExiting chat...")
+        return False
+    except EOFError:
+        print("\n\nExiting chat...")
+        return False
+
+    # Sample output (using anthropic.claude-3-haiku-20240307-v1:0):
+    # User:> Hi, my name is John.
+    # Bedrock agent: Hello John. How can I help you?
+    # User:> What is my name?
+    # Bedrock agent: Your name is John.
+
+
+if __name__ == "__main__":
+    asyncio.run(main())

python/samples/concepts/agents/bedrock_agent/bedrock_agent_with_code_interpreter.py

@@ -0,0 +1,77 @@
+# Copyright (c) Microsoft. All rights reserved.
+
+import asyncio
+import os
+
+from semantic_kernel.agents.bedrock.bedrock_agent import BedrockAgent
+from semantic_kernel.contents.binary_content import BinaryContent
+from semantic_kernel.contents.chat_message_content import ChatMessageContent
+
+# This sample shows how to interact with a Bedrock agent that is capable of writing and executing code.
+# This sample uses the following main component(s):
+# - a Bedrock agent
+# You will learn how to create a new Bedrock agent and ask it a question that requires coding to answer.
+# After running this sample, a bar chart will be generated and saved to a file in the same directory
+# as this script.
+
+AGENT_NAME = "semantic-kernel-bedrock-agent"
+INSTRUCTION = "You are a friendly assistant. You help people find information."
+
+
+ASK = """
+Create a bar chart for the following data:
+Panda   5
+Tiger   8 
+Lion    3
+Monkey  6
+Dolpin  2
+"""
+
+
+async def main():
+    bedrock_agent = await BedrockAgent.create(
+        AGENT_NAME,
+        instructions=INSTRUCTION,
+        enable_code_interpreter=True,
+    )
+
+    session_id = BedrockAgent.create_session_id()
+
+    # Placeholder for the file generated by the code interpreter
+    binary_item: BinaryContent | None = None
+
+    try:
+        # Invoke the agent
+        async for response in bedrock_agent.invoke(
+            session_id=session_id,
+            input_text=ASK,
+        ):
+            print(f"Response:\n{response}")
+            assert isinstance(response, ChatMessageContent)  # nosec
+            binary_item = next(item for item in response.items if isinstance(item, BinaryContent))
+    finally:
+        # Delete the agent
+        await bedrock_agent.delete_agent()
+
+    # Save the chart to a file
+    if not binary_item:
+        raise RuntimeError("No chart generated")
+
+    file_path = os.path.join(os.path.dirname(__file__), binary_item.metadata["name"])
+    binary_item.write_to_file(os.path.join(os.path.dirname(__file__), binary_item.metadata["name"]))
+    print(f"Chart saved to {file_path}")
+
+    # Sample output (using anthropic.claude-3-haiku-20240307-v1:0):
+    # Response:
+    # Here is the bar chart for the given data:
+    # [A bar chart showing the following data:
+    # Panda   5
+    # Tiger   8
+    # Lion    3
+    # Monkey  6
+    # Dolpin  2]
+    # Chart saved to ...
+
+
+if __name__ == "__main__":
+    asyncio.run(main())