やりたいこと

Bedrockの新機能、カスタムオーケストレーションリポジトリが公式のGitHub上に存在するのですが、1つ問題点があります。

一切ドキュメントがない！！！READMEすらない！！！

しかもこの機能めちゃくちゃ難しく、さらにリポジトリを見ても何をどうすればいいかよくわからない。

だったらAmazon Q DeveloperにREADMEを作ってもらおうじゃないか！ということでやってみました！

Amazon Q Developer Agentのドキュメント作成機能

2024年12月3日、Amazon Q Developerはソースコード内でドキュメントを生成できるようになりました。
この機能によって、Amazon Q Developer Agentが手間のかかるドキュメント作成のタスクを処理するため、開発者はコードの作成と設計に集中できます。

他にも、ユニットテスト作成機能や、コードレビュー機能も追加されています。まとめてブログ化されていました。
総じて、開発者がよりコーディングに集中できるような仕組みが整ってきています。

料金形態

Amazon Q Developerの機能の一部なので、この機能を使うからと言って特別追加で料金がかかることはありません。

Amazon Q Developerの料金形態としては、フリーティアとプロティアがあります。
フリーはもちろん無料、プロは1ユーザーあたり19ドル/月です。

フリーでも月10回呼び出せるそうなので、お試しするくらいなら無料で使えそうですね！
詳しくは↓

やってみる

まずはVSCode上にリポジトリをクローンします。
以下のコマンドをVSCodeのターミナルで叩きます。

git clone https://github.com/aws-samples/amazon-bedrock-samples.git

こんな感じになればOKです。

続いて、早速Amazon Q Developerの出番。

Amazon Q Developerのインストール手順については、以下のブログをご参照ください。
https://blog.serverworks.co.jp/2024/07/26/174241

入力欄に「/(スラッシュ)」を打つと、Amazon Q Developerのどの機能を使うかが選べます。

今回は /doc を選択し、エンターキーを押します。

すると、ドキュメント生成モードに移行します。
始めるには、Create a README か Update an existing fREADME かを選びます。
今回は前者を選択。

ClaudeHandsonディレクトリのREADMEは不要なので、Change folderを選択。

今回はもちろん、カスタムオーケストレーションのフォルダーを選択します。

再度確認されるので、Yes を選択。

すると、実行開始してくれます。
実行手順としては、3段階あるようです。

ソースファイルの読み取り
ソースファイルの要約
ドキュメントの生成

数分待つと完了し、実際にREADMEが生成されていました！

実際に生成されたドキュメントはこちら(長いので折りたたんでいます)

Amazon Bedrock Agent with Custom Orchestration

This project demonstrates how to create and use a Bedrock Agent with custom orchestration for managing restaurant bookings. It showcases the integration of AWS services like Lambda, DynamoDB, and Amazon Bedrock to create an intelligent conversational agent.

The custom orchestration feature allows for fine-grained control over the agent's behavior, enabling complex conversation flows and integration with external tools and services.

Repository Structure

agents.py: Main script for creating and managing Bedrock agents, including IAM roles and Lambda functions.
knowledge_bases.py: Helper class for creating and managing Knowledge Bases for Amazon Bedrock.
lambda_function.py: Lambda function for handling restaurant booking operations.
lambda_rewoo.py: Custom orchestration Lambda function for the Bedrock agent.
custom_orchestrators_samples/: Directory containing sample custom orchestrators:
- lambda_react.js: JavaScript implementation of a React-based orchestrator.
- lambda_react.py: Python implementation of a React-based orchestrator.
- lambda_rewoo.js: JavaScript implementation of a ReWOO-based orchestrator.

Usage Instructions

Prerequisites

AWS CLI configured with appropriate permissions
Python 3.11 or later
Boto3 library installed
Access to Amazon Bedrock and related services

Setting Up the Environment

Clone the repository:

git clone <repository-url>
cd amazon-bedrock-samples/agents-and-function-calling/bedrock-agents/features-examples/14-create-agent-with-custom-orchestration

Install required Python packages:

pip install boto3 opensearch-py retrying

Ensure you have the necessary AWS permissions to create and manage Bedrock agents, Lambda functions, DynamoDB tables, and IAM roles.

Creating a Bedrock Agent with Custom Orchestration

Modify the agents.py script to set your desired agent configuration:
- Agent name
- Description
- Foundation model
- Instruction
- Custom orchestration Lambda function (if using)
Run the agents.py script:
```
python agents.py
```
The script will create:
- A DynamoDB table for storing restaurant bookings
- A Lambda function for handling booking operations
- IAM roles and policies
- A Bedrock agent with custom orchestration

Using the Agent

Once the agent is created, you can interact with it using the Bedrock Agent Runtime API or through the AWS Console. The agent can handle restaurant booking operations such as:

Creating a new booking
Retrieving booking details
Deleting a booking

Example interaction:

response = bedrock_agent_runtime_client.invoke_agent(
    agentId='your-agent-id',
    agentAliasId='your-agent-alias-id',
    sessionId='unique-session-id',
    inputText='I want to book a table for 4 people tomorrow at 7 PM'
)
print(response['completion'])

Data Flow

User input is received by the Bedrock Agent.
The custom orchestration Lambda function (lambda_rewoo.py or one of the samples in custom_orchestrators_samples/) processes the input and determines the next action.
If a booking operation is required, the orchestrator invokes the booking Lambda function (lambda_function.py).
The booking Lambda function interacts with the DynamoDB table to create, retrieve, or delete bookings.
The result is returned to the orchestrator, which then formulates a response.
The Bedrock Agent sends the final response back to the user.

User Input -> Bedrock Agent -> Custom Orchestrator -> Booking Lambda -> DynamoDB
                    ^                    |
                    |                    v
                    User <---- Bedrock Agent <---- Custom Orchestrator

Troubleshooting

If you encounter permission issues, ensure that the IAM roles have the correct policies attached.
Check CloudWatch Logs for Lambda function execution logs to debug any issues.
Verify that the DynamoDB table is created correctly and accessible to the Lambda function.

Infrastructure

The project uses the following AWS resources:

Lambda:
- lambda_function: Handles restaurant booking operations
- Custom orchestration Lambda (e.g., lambda_rewoo)
DynamoDB:
- Table for storing restaurant bookings
IAM:
- Roles for Lambda functions and Bedrock agent
Amazon Bedrock:
- Bedrock agent with custom orchestration

Deployment

The agents.py script handles the deployment of all necessary resources. Ensure you have the required AWS permissions before running the script.

For production deployments, consider using AWS CloudFormation or AWS CDK to manage the infrastructure as code.

日本語翻訳版はこちらです(長いので折りたたんでいます)

カスタムオーケストレーションを使用したAmazon Bedrock Agent

このプロジェクトは、レストランの予約管理のためのカスタムオーケストレーション機能を持つBedrock Agentの作成方法と使用方法を示しています。Lambda、DynamoDB、Amazon BedrockなどのAWSサービスを統合して、インテリジェントな対話型エージェントを作成する方法を紹介します。

カスタムオーケストレーション機能により、エージェントの動作を細かく制御でき、複雑な会話フローと外部ツールやサービスとの統合を実現できます。

リポジトリ構造

agents.py: Bedrockエージェントの作成と管理のためのメインスクリプト（IAMロールとLambda関数を含む）
knowledge_bases.py: Amazon Bedrockのナレッジベースを作成・管理するためのヘルパークラス
lambda_function.py: レストラン予約操作を処理するためのLambda関数
lambda_rewoo.py: Bedrockエージェント用のカスタムオーケストレーションLambda関数
custom_orchestrators_samples/: サンプルカスタムオーケストレーターを含むディレクトリ：
- lambda_react.js: ReactベースのオーケストレーターのJavaScript実装
- lambda_react.py: ReactベースのオーケストレーターのPython実装
- lambda_rewoo.js: ReWOOベースのオーケストレーターのJavaScript実装

使用方法

前提条件

適切な権限で設定されたAWS CLI
Python 3.11以降
Boto3ライブラリがインストールされていること
Amazon Bedrockおよび関連サービスへのアクセス権限

環境のセットアップ

リポジトリをクローン：

git clone <repository-url>
cd amazon-bedrock-samples/agents-and-function-calling/bedrock-agents/features-examples/14-create-agent-with-custom-orchestration

必要なPythonパッケージをインストール：
```
pip install boto3 opensearch-py retrying
```
Bedrockエージェント、Lambda関数、DynamoDBテーブル、IAMロールを作成および管理するための必要なAWS権限があることを確認してください。

カスタムオーケストレーション付きBedrockエージェントの作成

agents.pyスクリプトを以下の設定で変更：
- エージェント名
- 説明
- 基盤モデル
- インストラクション
- カスタムオーケストレーションLambda関数（使用する場合）
agents.pyスクリプトを実行：
```
python agents.py
```
スクリプトは以下を作成します：
- レストラン予約を保存するためのDynamoDBテーブル
- 予約操作を処理するためのLambda関数
- IAMロールとポリシー
- カスタムオーケストレーション付きBedrockエージェント

エージェントの使用

エージェントが作成されたら、Bedrock Agent Runtime APIまたはAWSコンソールを使用して対話できます。エージェントは以下のようなレストラン予約操作を処理できます：

新規予約の作成
予約詳細の取得
予約の削除

対話例：

response = bedrock_agent_runtime_client.invoke_agent(
    agentId='your-agent-id',
    agentAliasId='your-agent-alias-id',
    sessionId='unique-session-id',
    inputText='明日の午後7時に4人で予約したいです'
)
print(response['completion'])

データフロー

ユーザー入力がBedrockエージェントによって受信されます。
カスタムオーケストレーションLambda関数（lambda_rewoo.pyまたはcustom_orchestrators_samples/内のサンプルのいずれか）が入力を処理し、次のアクションを決定します。
予約操作が必要な場合、オーケストレーターは予約Lambda関数（lambda_function.py）を呼び出します。
予約Lambda関数はDynamoDBテーブルと連携して、予約の作成、取得、削除を行います。
結果はオーケストレーターに返され、応答が作成されます。
Bedrockエージェントがユーザーに最終応答を送信します。

ユーザー入力 -> Bedrockエージェント -> カスタムオーケストレーター -> 予約Lambda -> DynamoDB
                     ^                    |
                     |                    v
                     ユーザー <---- Bedrockエージェント <---- カスタムオーケストレーター

トラブルシューティング

権限の問題が発生した場合は、IAMロールに正しいポリシーが付与されていることを確認してください。
問題をデバッグするには、CloudWatch LogsでLambda関数の実行ログを確認してください。
DynamoDBテーブルが正しく作成され、Lambda関数からアクセス可能であることを確認してください。

インフラストラクチャ

このプロジェクトは以下のAWSリソースを使用します：

Lambda：
- lambda_function: レストラン予約操作を処理
- カスタムオーケストレーションLambda（例：lambda_rewoo）
DynamoDB：
- レストラン予約を保存するためのテーブル
IAM：
- Lambda関数とBedrockエージェント用のロール
Amazon Bedrock：
- カスタムオーケストレーション付きBedrockエージェント

デプロイメント

agents.pyスクリプトが必要なリソースすべてのデプロイメントを処理します。スクリプトを実行する前に、必要なAWS権限があることを確認してください。

本番環境へのデプロイメントでは、AWS CloudFormationまたはAWS CDKを使用してインフラストラクチャをコードとして管理することを検討してください。

これが一瞬で作られるって、もしかしたらとんでもない時代が来たかもしれません…

ちなみにですが、気に入らない場所があったら修正もしてくれるそうです。
今回は Make change としてみます。

ここでは自由記述で依頼できるそうです。
先ほど作成してくれたドキュメントの中で、
「Creating a Bedrock Agent with Custom Orchestration がわかりにくかったので、1つ1つの手順をよりわかりやすく、丁寧に説明してください」
と依頼してみます。

すると再び思考し…

READMEがアップデートされました！

変更箇所だけ抜き出してみます。

更新された英語版(長いので折りたたんでいます)

Creating a Bedrock Agent with Custom Orchestration

The process of creating a Bedrock Agent with custom orchestration involves several steps, each handled by functions in the agents.py script. Here's a detailed breakdown of the process:

Configure the agent settings:
Open the agents.py script and modify the following variables at the top of the script:
- agent_name: Choose a unique name for your agent
- agent_description: Provide a brief description of your agent's purpose
- agent_foundation_model: Specify the foundation model to use (e.g., "anthropic.claude-v2")
- agent_instruction: Define the primary instruction for your agent
- custom_orchestration_lambda: Set to None if not using custom orchestration, or provide the Lambda function name if using custom orchestration
Create a DynamoDB table:
The script uses the create_dynamodb function to create a table for storing restaurant bookings. This table will be used by the booking Lambda function.
```
create_dynamodb(table_name, 'booking_id')
```
Create an IAM role for the Lambda function:
The create_lambda_role function sets up an IAM role with the necessary permissions for the Lambda function to access DynamoDB and other required services.
```
lambda_iam_role = create_lambda_role(agent_name)
```

Create the booking Lambda function:
The create_lambda function packages and deploys the Lambda function that handles booking operations.

lambda_function = create_lambda(
    lambda_function_name,
    'lambda_function.py',
    lambda_iam_role,
    environment={'Variables': {'booking_table_name': table_name}}
)

(Optional) Create the custom orchestration Lambda function:
If using custom orchestration, another Lambda function is created to handle the orchestration logic.
```
custom_orchestration_lambda = create_lambda(
    custom_orchestration_lambda_name,
    'lambda_rewoo.py',
    lambda_iam_role
)
```
Create an IAM role for the Bedrock Agent:
The script sets up an IAM role that allows the Bedrock Agent to invoke Lambda functions and access other necessary resources.

Create the Bedrock Agent:
The create_agent_object function is called to create the Bedrock Agent with the specified configuration, including custom orchestration if enabled.

agent_id = create_agent_object(
    agent_name, agent_role, agent_description,
    idle_session_ttl_in_seconds, agent_foundation_model,
    agent_instruction, custom_orchestration_lambda, None
)

Create an alias for the Bedrock Agent:
An alias is created for the agent to make it easier to manage different versions.

alias_id = bedrock_agent_client.create_agent_alias(
    agentId=agent_id,
    agentAliasName=f'{agent_name}-alias'
)['agentAlias']['agentAliasId']

Run the script:
Execute the agents.py script to create all the necessary resources and the Bedrock Agent:
```
python agents.py
```
The script will output progress information and any errors encountered during the creation process.
Verify the agent creation:
After the script completes, you can verify the agent's creation in the AWS Console or by using the Bedrock Agent API.

By following these steps, you'll create a Bedrock Agent with custom orchestration, including all the necessary AWS resources like DynamoDB tables, Lambda functions, and IAM roles. The agent will be ready to handle restaurant booking operations using the custom logic defined in the orchestration Lambda function.

更新された日本語版(長いので折りたたんでいます)

環境のセットアップ

リポジトリをクローン：

git clone <repository-url>
cd amazon-bedrock-samples/agents-and-function-calling/bedrock-agents/features-examples/14-create-agent-with-custom-orchestration

必要なPythonパッケージをインストール：
```
pip install boto3 opensearch-py retrying
```
Bedrockエージェント、Lambda関数、DynamoDBテーブル、IAMロールの作成と管理に必要なAWS権限があることを確認してください。

カスタムオーケストレーション付きBedrockエージェントの作成

カスタムオーケストレーション付きBedrockエージェントの作成プロセスは、agents.pyスクリプト内の関数によって処理される複数のステップで構成されています。以下に詳細な手順を説明します：

エージェント設定の構成：
agents.pyスクリプトを開き、スクリプト上部の以下の変数を変更します：
- agent_name：エージェントの一意の名前を選択
- agent_description：エージェントの目的の簡単な説明
- agent_foundation_model：使用する基盤モデルを指定（例：「anthropic.claude-v2」）
- agent_instruction：エージェントの主要な指示を定義
- custom_orchestration_lambda：カスタムオーケストレーションを使用しない場合はNone、使用する場合はLambda関数名を指定
DynamoDBテーブルの作成：
スクリプトはcreate_dynamodb関数を使用してレストラン予約保存用のテーブルを作成します。このテーブルは予約Lambda関数によって使用されます。
```
create_dynamodb(table_name, 'booking_id')
```
Lambda関数用のIAMロールの作成：
create_lambda_role関数は、Lambda関数がDynamoDBやその他の必要なサービスにアクセスするために必要な権限を持つIAMロールを設定します。
```
lambda_iam_role = create_lambda_role(agent_name)
```

予約Lambda関数の作成：
create_lambda関数は、予約操作を処理するLambda関数をパッケージ化してデプロイします。

lambda_function = create_lambda(
    lambda_function_name,
    'lambda_function.py',
    lambda_iam_role,
    environment={'Variables': {'booking_table_name': table_name}}
)

（オプション）カスタムオーケストレーションLambda関数の作成：
カスタムオーケストレーションを使用する場合、オーケストレーションロジックを処理する別のLambda関数が作成されます。
```
custom_orchestration_lambda = create_lambda(
    custom_orchestration_lambda_name,
    'lambda_rewoo.py',
    lambda_iam_role
)
```
BedrockエージェントのIAMロールの作成：
スクリプトは、BedrockエージェントがLambda関数を呼び出し、他の必要なリソースにアクセスできるようにするIAMロールを設定します。
Bedrockエージェントの作成：
create_agent_object関数を呼び出して、カスタムオーケストレーション（有効な場合）を含む指定された設定でBedrockエージェントを作成します。
```
agent_id = create_agent_object(
    agent_name, agent_role, agent_description,
    idle_session_ttl_in_seconds, agent_foundation_model,
    agent_instruction, custom_orchestration_lambda, None
)
```
Bedrockエージェントのエイリアスの作成：
異なるバージョンを簡単に管理できるように、エージェントのエイリアスを作成します。
```
alias_id = bedrock_agent_client.create_agent_alias(
    agentId=agent_id,
    agentAliasName=f'{agent_name}-alias'
)['agentAlias']['agentAliasId']
```
スクリプトの実行：
必要なリソースとBedrockエージェントを作成するために、agents.pyスクリプトを実行します：
```
python agents.py
```
スクリプトは作成プロセス中の進行状況とエラー（もしあれば）を出力します。
エージェント作成の確認：
スクリプトの完了後、AWSコンソールまたはBedrock Agent APIを使用してエージェントの作成を確認できます。

これらの手順に従うことで、DynamoDBテーブル、Lambda関数、IAMロールなどの必要なAWSリソースを含む、カスタムオーケストレーション付きBedrockエージェントが作成されます。エージェントはオーケストレーションLambda関数で定義されたカスタムロジックを使用してレストラン予約操作を処理できる状態になります。

め、めっちゃ詳細に解説してくれてる〜〜〜！！！

ということでこれでOKでしょう！Accept します！

あっさりとREADMEが完成しました！

これを実際に試すのはまた別記事で！

まとめ

めちゃくちゃ簡単にREADMEを作成してくれました！
ここまで来ると、最早こんなに簡単でいいのか？って感じです。

技術的負債の解消に一役買ってくれそうな機能だと思います！
あとは、もっと大規模で複雑なシステムになった時にどこまで正確に解釈して文字起こししてくれるか、でしょうか…

今後の動向にも注目です！