Amazon Q Developerのドキュメント作成機能を使ってみた！

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

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

https://github.com/aws-samples/amazon-bedrock-samples/tree/main/agents-and-function-calling/bedrock-agents/features-examples/14-create-agent-with-custom-orchestration

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

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

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

https://aws.amazon.com/about-aws/whats-new/2024/12/amazon-q-developer-generate-documentation-source-code/

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

https://aws.amazon.com/blogs/aws/new-amazon-q-developer-agent-capabilities-include-generating-documentation-code-reviews-and-unit-tests/

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

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

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

https://aws.amazon.com/q/developer/pricing/

# やってみる
まずはVSCode上にリポジトリをクローンします。
以下のコマンドをVSCodeのターミナルで叩きます。
```
git clone https://github.com/aws-samples/amazon-bedrock-samples.git
```

こんな感じになればOKです。
![image.png](https://qiita-image-store.s3.ap-northeast-1.amazonaws.com/0/3616210/5fdaa811-0ddc-f483-531a-fd547d33dd39.png)

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

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

入力欄に「/(スラッシュ)」を打つと、Amazon Q Developerのどの機能を使うかが選べます。
![image.png](https://qiita-image-store.s3.ap-northeast-1.amazonaws.com/0/3616210/c30a796e-e2a6-e51a-89ce-818066473e12.png)

今回は `/doc` を選択し、エンターキーを押します。
![image.png](https://qiita-image-store.s3.ap-northeast-1.amazonaws.com/0/3616210/c02bc7a2-ba52-e5be-5299-118d3d15e2f5.png)

すると、ドキュメント生成モードに移行します。
始めるには、`Create a README` か `Update an existing fREADME` かを選びます。
今回は前者を選択。
![image.png](https://qiita-image-store.s3.ap-northeast-1.amazonaws.com/0/3616210/035bb31c-ac10-6dff-1279-195a87b58314.png)

ClaudeHandsonディレクトリのREADMEは不要なので、`Change folder`を選択。
![image.png](https://qiita-image-store.s3.ap-northeast-1.amazonaws.com/0/3616210/258b5fa0-eb32-81ed-bc1b-36cd97db6eee.png)

今回はもちろん、カスタムオーケストレーションのフォルダーを選択します。
![image.png](https://qiita-image-store.s3.ap-northeast-1.amazonaws.com/0/3616210/44946f3a-a546-8a4f-457b-2a6d0fe268bb.png)

再度確認されるので、`Yes` を選択。
![image.png](https://qiita-image-store.s3.ap-northeast-1.amazonaws.com/0/3616210/59c55eb8-f65c-6c5b-01a7-8172fcc48801.png)

すると、実行開始してくれます。
実行手順としては、3段階あるようです。
1. ソースファイルの読み取り
1. ソースファイルの要約
1. ドキュメントの生成

![image.png](https://qiita-image-store.s3.ap-northeast-1.amazonaws.com/0/3616210/239fd45a-3d97-eef1-c042-109311b2ef7f.png)

数分待つと完了し、実際にREADMEが生成されていました！
![image.png](https://qiita-image-store.s3.ap-northeast-1.amazonaws.com/0/3616210/5ea35023-a929-ca53-f373-c2ad2910a236.png)

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


# 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

1. 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
   ```

2. Install required Python packages:
   ```
   pip install boto3 opensearch-py retrying
   ```

3. 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

1. Modify the `agents.py` script to set your desired agent configuration:
   - Agent name
   - Description
   - Foundation model
   - Instruction
   - Custom orchestration Lambda function (if using)

2. Run the `agents.py` script:
   ```
   python agents.py
   ```

3. 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:
```python
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

1. User input is received by the Bedrock Agent.
2. 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.
3. If a booking operation is required, the orchestrator invokes the booking Lambda function (`lambda_function.py`).
4. The booking Lambda function interacts with the DynamoDB table to create, retrieve, or delete bookings.
5. The result is returned to the orchestrator, which then formulates a response.
6. 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.

</details>

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

# カスタムオーケストレーションを使用した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および関連サービスへのアクセス権限

### 環境のセットアップ

1. リポジトリをクローン：
   ```
   git clone <repository-url>
   cd amazon-bedrock-samples/agents-and-function-calling/bedrock-agents/features-examples/14-create-agent-with-custom-orchestration
   ```

2. 必要なPythonパッケージをインストール：
   ```
   pip install boto3 opensearch-py retrying
   ```

3. Bedrockエージェント、Lambda関数、DynamoDBテーブル、IAMロールを作成および管理するための必要なAWS権限があることを確認してください。

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

1. `agents.py`スクリプトを以下の設定で変更：
   - エージェント名
   - 説明
   - 基盤モデル
   - インストラクション
   - カスタムオーケストレーションLambda関数（使用する場合）

2. `agents.py`スクリプトを実行：
   ```
   python agents.py
   ```

3. スクリプトは以下を作成します：
   - レストラン予約を保存するためのDynamoDBテーブル
   - 予約操作を処理するためのLambda関数
   - IAMロールとポリシー
   - カスタムオーケストレーション付きBedrockエージェント

### エージェントの使用

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

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

対話例：
```python
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'])
```

## データフロー

1. ユーザー入力がBedrockエージェントによって受信されます。
2. カスタムオーケストレーションLambda関数（`lambda_rewoo.py`または`custom_orchestrators_samples/`内のサンプルのいずれか）が入力を処理し、次のアクションを決定します。
3. 予約操作が必要な場合、オーケストレーターは予約Lambda関数（`lambda_function.py`）を呼び出します。
4. 予約Lambda関数はDynamoDBテーブルと連携して、予約の作成、取得、削除を行います。
5. 結果はオーケストレーターに返され、応答が作成されます。
6. 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を使用してインフラストラクチャをコードとして管理することを検討してください。

</details>

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

ちなみにですが、気に入らない場所があったら修正もしてくれるそうです。
今回は `Make change` としてみます。
![image.png](https://qiita-image-store.s3.ap-northeast-1.amazonaws.com/0/3616210/c0fa01cd-ca33-6c23-79dd-5d4561206fdd.png)

ここでは自由記述で依頼できるそうです。
先ほど作成してくれたドキュメントの中で、
「`Creating a Bedrock Agent with Custom Orchestration` がわかりにくかったので、1つ1つの手順をよりわかりやすく、丁寧に説明してください」
と依頼してみます。
![image.png](https://qiita-image-store.s3.ap-northeast-1.amazonaws.com/0/3616210/818ac67c-d1df-2830-1e05-e5ebbdf3eb65.png)

すると再び思考し…
![image.png](https://qiita-image-store.s3.ap-northeast-1.amazonaws.com/0/3616210/b927964d-25b0-e775-c3d0-dfaf778da7c1.png)

READMEがアップデートされました！
![image.png](https://qiita-image-store.s3.ap-northeast-1.amazonaws.com/0/3616210/166b3f90-1225-e8d1-eb34-424f787090fc.png)

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

<details><summary>更新された英語版(長いので折りたたんでいます)</summary>

### 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:

1. 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

2. 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.
   ```python
   create_dynamodb(table_name, 'booking_id')
   ```

3. 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.
   ```python
   lambda_iam_role = create_lambda_role(agent_name)
   ```

4. Create the booking Lambda function:
   The `create_lambda` function packages and deploys the Lambda function that handles booking operations.
   ```python
   lambda_function = create_lambda(
       lambda_function_name,
       'lambda_function.py',
       lambda_iam_role,
       environment={'Variables': {'booking_table_name': table_name}}
   )
   ```

5. (Optional) Create the custom orchestration Lambda function:
   If using custom orchestration, another Lambda function is created to handle the orchestration logic.
   ```python
   custom_orchestration_lambda = create_lambda(
       custom_orchestration_lambda_name,
       'lambda_rewoo.py',
       lambda_iam_role
   )
   ```

6. 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.

7. 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.
   ```python
   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
   )
   ```

8. Create an alias for the Bedrock Agent:
   An alias is created for the agent to make it easier to manage different versions.
   ```python
   alias_id = bedrock_agent_client.create_agent_alias(
       agentId=agent_id,
       agentAliasName=f'{agent_name}-alias'
   )['agentAlias']['agentAliasId']
   ```

9. 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.

10. 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.


</details>

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

### 環境のセットアップ

1. リポジトリをクローン：
   ```
   git clone <repository-url>
   cd amazon-bedrock-samples/agents-and-function-calling/bedrock-agents/features-examples/14-create-agent-with-custom-orchestration
   ```

2. 必要なPythonパッケージをインストール：
   ```
   pip install boto3 opensearch-py retrying
   ```

3. Bedrockエージェント、Lambda関数、DynamoDBテーブル、IAMロールの作成と管理に必要なAWS権限があることを確認してください。

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

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

1. エージェント設定の構成：
   `agents.py`スクリプトを開き、スクリプト上部の以下の変数を変更します：
   - `agent_name`：エージェントの一意の名前を選択
   - `agent_description`：エージェントの目的の簡単な説明
   - `agent_foundation_model`：使用する基盤モデルを指定（例：「anthropic.claude-v2」）
   - `agent_instruction`：エージェントの主要な指示を定義
   - `custom_orchestration_lambda`：カスタムオーケストレーションを使用しない場合は`None`、使用する場合はLambda関数名を指定

2. DynamoDBテーブルの作成：
   スクリプトは`create_dynamodb`関数を使用してレストラン予約保存用のテーブルを作成します。このテーブルは予約Lambda関数によって使用されます。
   ```python
   create_dynamodb(table_name, 'booking_id')
   ```

3. Lambda関数用のIAMロールの作成：
   `create_lambda_role`関数は、Lambda関数がDynamoDBやその他の必要なサービスにアクセスするために必要な権限を持つIAMロールを設定します。
   ```python
   lambda_iam_role = create_lambda_role(agent_name)
   ```

4. 予約Lambda関数の作成：
   `create_lambda`関数は、予約操作を処理するLambda関数をパッケージ化してデプロイします。
   ```python
   lambda_function = create_lambda(
       lambda_function_name,
       'lambda_function.py',
       lambda_iam_role,
       environment={'Variables': {'booking_table_name': table_name}}
   )
   ```

5. （オプション）カスタムオーケストレーションLambda関数の作成：
   カスタムオーケストレーションを使用する場合、オーケストレーションロジックを処理する別のLambda関数が作成されます。
   ```python
   custom_orchestration_lambda = create_lambda(
       custom_orchestration_lambda_name,
       'lambda_rewoo.py',
       lambda_iam_role
   )
   ```

6. BedrockエージェントのIAMロールの作成：
   スクリプトは、BedrockエージェントがLambda関数を呼び出し、他の必要なリソースにアクセスできるようにするIAMロールを設定します。

7. Bedrockエージェントの作成：
   `create_agent_object`関数を呼び出して、カスタムオーケストレーション（有効な場合）を含む指定された設定でBedrockエージェントを作成します。
   ```python
   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
   )
   ```

8. Bedrockエージェントのエイリアスの作成：
   異なるバージョンを簡単に管理できるように、エージェントのエイリアスを作成します。
   ```python
   alias_id = bedrock_agent_client.create_agent_alias(
       agentId=agent_id,
       agentAliasName=f'{agent_name}-alias'
   )['agentAlias']['agentAliasId']
   ```

9. スクリプトの実行：
   必要なリソースとBedrockエージェントを作成するために、`agents.py`スクリプトを実行します：
   ```
   python agents.py
   ```

   スクリプトは作成プロセス中の進行状況とエラー（もしあれば）を出力します。

10. エージェント作成の確認：
    スクリプトの完了後、AWSコンソールまたはBedrock Agent APIを使用してエージェントの作成を確認できます。

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

</details>

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

ということでこれでOKでしょう！`Accept` します！
![image.png](https://qiita-image-store.s3.ap-northeast-1.amazonaws.com/0/3616210/e6ac9a8f-81b2-4285-ce1e-7eb7e4fe4f11.png)

あっさりとREADMEが完成しました！
![image.png](https://qiita-image-store.s3.ap-northeast-1.amazonaws.com/0/3616210/ab550651-2f34-f737-e715-ff0495e8d1c6.png)

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

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

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

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