はじめに

2025年は AI Agent や MCP (Model Context Protocol) といった技術が注目を集めています。これらは、複数の外部システムと連携しながら、対話的にタスクを実行する“拡張可能なAI”を実現するための重要な要素です。

今回から、AI Agent を使って Knowledge Base と Asana MCP Server を連携させることで、AI がどのように情報を取得・処理・応答するのかを段階的に確認していきます。今回はローカル環境での動作確認を前提として、Terraform による AWS リソースの構築から始め、最終的に AI Agent の仕組みを理解することを目指します。

本シリーズの構成このブログは全3回構成でお届けします。

AWS 環境構築編 - Part 1
- Terraform を用いた AWS 環境の構築を行い、ベクターDB（Aurora PostgreSQL）と Knowledge Base の初期設定・動作確認を行います。
実践編 - Part 2
- 構築済みの環境を使って、ローカルでコンテナを起動し、AI Agent が Asana MCP Server や Knowledge Base と連携して動作する様子を実際に確認します。
解説編 - Part 3
- AI Agent の内部構造や、MCP Server を通じた外部API連携、ベクター検索による回答生成の流れを技術的に解説します。

ハンズオンで構築するアプリケーションの全体像

このシリーズを通して、以下の機能を統合したAIエージェントアプリケーションを構築し、ローカル環境で動作させます。

AWS上のKnowledge Base（RAG）からの情報参照や、Asana MCPサーバーを通じてAsanaのタスクが操作を行えます。

なお、本ハンズオンではフロントエンドUIは構築しません。動作確認は、curlコマンド等でバックエンドに直接APIリクエストを送信して行いますので、あらかじめご了承ください。

前提

ハンズオン動作環境

このハンズオンは以下の環境で動作確認をしています

ハンズオン用 GitHub レポジトリ

GitHub - yapodu-inc/ypd-langchain-agent-hands-on: 株式会社ヤポドゥAIエージェント開発の基礎ハンズオン用レポジトリ

推奨環境（Windows）

Windows 11 Pro
WSL2 / Ubuntu 24.04
- Docker 公式手順で Docker インストール済み
- $ docker compose version で 2.系が出力される

macOS での実施について

本ハンズオンは Linux 環境を前提に作成されていますが、Docker Desktopがインストールされた macOS でも実施可能です。ただし、一部のコマンドやパスの指定方法が異なる場合があります。

必要なツール

Docker および Docker Compose v2.x
- Compose は公式手順であればオプションとしてインストールされています。
Git
VS Code
Terraform

AWS アカウント

以下のいずれも AdministratorAccess 相当の権限を持つ必要があります。

マネジメントコンソールへのアクセス権（UI操作用）
Terraform ・ AWS CLI を使用するための API 認証情報（アクセスキー・シークレットキーなど）

Asana アカウント

Asana の Personal Access Token を取得済みであること。

参加者の前提スキル

AWS CLI 用の環境変数を設定できる
Docker の基本操作を理解している
- 例: docker build, docker run, docker compose up
Terraform の基本的なコマンドを理解している
- terraform init, plan, apply の一連の流れを説明できる、または実行した経験がある

Part 1: 環境構築の実践

tfstate 用 S3 バケット作成

Terraform の tfstate（状態ファイル）を管理するための S3 バケットを作成します。
tfstate は、Terraform がインフラの現在の構成を追跡するために使用する重要な情報です。

Region 指定

マネージメントコンソールの AWS region を us-west-2 (オレゴン) に指定

CloudShell を起動する

環境変数にオレゴンが設定されていることを確認

~ $ echo $AWS_REGION
us-west-2

tfstate 用 S3 バケット手動作成

CloudShell で tfstate 用 S3 バケットを作成します。

CloudShell 上で以下のコマンドを実行して、任意の名前（例として AWS アカウント ID を含めたもの）で S3 バケットを作成します。

~$ aws s3 mb s3://yapodu-hands-on-$(aws sts get-caller-identity --query Account --output text) --region us-west-2

バケット名は Terraform のコードに記載するため、テキスト等に控えてくおいて下さい。

作成後にマネージメントコンソールの
[ S3 ] -> [ 汎用バケット ]
に作成したバケット名が表示されていることを確認して下さい。

terraform apply 前確認

terraform apply を実行する前に、準備と確認を行います。

git clone と VS Code 起動

ハンズオン用のリポジトリをローカル環境にクローンします。

$ git clone https://github.com/yapodu-inc/ypd-langchain-agent-hands-on.git

クローン完了後、VS Code でプロジェクトを開きます

$ cd ypd-langchain-agent-hands-on
$ code .

VS Code が起動したら、以下の構成を確認してください
terraform/ - AWS リソース定義（Part 1 で使用）
ypd-langchain/ - AI エージェントアプリケーション（Part 2 で使用）
doc/ - ドキュメントとサンプルデータ

Terraformの version 確認

今回のハンズオンでは Terraform 1.12.1 を使用します。 WSL2 上で Terraform のバージョンが一致しているか確認し、未インストールまたは異なるバージョンの際はインストールして下さい。

WSL2での確認例

$ terraform version 
Terraform v1.12.1
on linux_amd64

tfenv で version 指定する例

以下は tfenv を使用したバージョン指定の Terraform インストール方法です。

tfenv インストール

$ git clone https://github.com/tfutils/tfenv.git ~/.tfenv

tfenv パス指定

$ echo 'export PATH="$HOME/.tfenv/bin:$PATH"' >> ~/.bashrc
$ source ~/.bashrc

Terraform 1.12.1のインストールと確認

$ tfenv install 1.12.1
$ tfenv use 1.12.1
$ terraform --version

terraform backend の修正

terraform/environment/dev-ypd/default/backend_dev-ypd.tf の bucket を CloudShell で作成したバケット名に修正して下さい。

# bucket= 作成したS3バケットの名前を指定して下さい。
terraform {
  backend "s3" {
    bucket = "terraform-backend-yapodu-ai-bot-123456789012"
    key    = "terraform/state/yapodu-ai-bot/ypd-dev/default/terraform.tfstate"
    region = "us-west-2"
  }
}

AWS用環境変数の設定

ローカル環境にAWS用の環境変数を設定して下さい。

本来、Terraform を実行する際に環境変数による認証情報の指定は非推奨ですが、本ハンズオンではセットアップを簡易にするため、この手順を採用します。

AWS 関連環境変数

AWS_ACCESS_KEY_ID
AWS_SECRET_ACCESS_KEY
AWS_REGION
AWS_SESSION_TOKEN(一時認証情報の場合)

AWS CLI 確認

Terraform 実行前に AWS CLI を実行し AWS 認証情報が設定されていること、 S3 バケット名が表示されることを確認して下さい。

AWS 認証情報

$ aws sts get-caller-identity

成功時の出力例

{
    "UserId": "AROACCCCCCCCCCCCCCCCC:example.example-ac@yapodu.co.jp",
    "Account": "123456789012",
    "arn:aws:iam::123456789012:user/example-ac"
}

S3 一覧

$ aws s3 ls

成功時の出力例
作成した S3 バケット名が出力されていることを確認して下さい。

2025-06-07 11:49:47 yapodu-hands-on-123456789012

terraform init 実行

Terraform のプロバイダーやバックエンドを初期化し、必要なプラグイン / モジュールをダウンロードするために init を実行します。

$ cd terraform/environment/dev-ypd/default
$ terraform init

成功時の出力例

Terraform has been successfully initialized!

You may now begin working with Terraform. Try running "terraform plan" to see
any changes that are required for your infrastructure. All Terraform commands
should now work.

If you ever set or change modules or backend configuration for Terraform,
rerun this command to reinitialize your working directory. If you forget, other
commands will detect it and remind you to do so if necessary.

init 実行後の validate & plan 確認

terraform validate で構文エラーがないかを確認し、terraform plan でこれから適用されるリソースの内容を事前確認します。

validate 実行

$ terraform validate

成功時の出力例

Success! The configuration is valid.

plan 実行

$ terraform plan

成功時の出力例

Plan: 39 to add, 0 to change, 0 to destroy.

Note: You didn't use the -out option to save this plan, so Terraform can't guarantee to take exactly these actions if you run "terraform apply" now.

※plan を確認することで、意図しないリソース作成・削除を未然に防ぐことができます。必要に応じて追記も可能です。

apply 実行

準備が完了したので、terraform apply を実行してインフラを構築します。

terraform apply

実行内容が表示されたあと、以下のようなプロンプトが表示されます。
プロンプトで表示される内容を確認し、yes と入力することでリソースの作成が開始されます

Do you want to perform these actions?
  Terraform will perform the actions described above.
  Only 'yes' will be accepted to approve.

  Enter a value: yes

成功時の出力例

aws_rds_cluster_instance.main_db_01: Still creating... [09m00s elapsed]
aws_rds_cluster_instance.main_db_01: Creation complete after 9m3s [id=ypd-dev-aurora-main]

Apply complete! Resources: 39 added, 0 changed, 0 destroyed.

terraform apply によって AWS リソースの第1段が作成されました。続いて PostgreSQL の設定を行います

Knowledge Base 用のベクターデータベース設定（Aurora PostgreSQL）

terraform apply が完了すると、AWS コンソールの
[ RDS ] -> [データベース ]
に Aurora クラスター ypd-dev-aurora-main-cluster が作成されています。この Aurora PostgreSQL を、Amazon Bedrock Knowledge Base のベクターデータベースとして使用するための設定を行います。

Data API 経由で必要な PostgreSQL 拡張機能（pgvector）と、埋め込みベクトル保存用のテーブルを作成します。
以下の手順のリソース名を作成されたリソース名へ置き換えて実行してください。

1. 必要情報取得

1.1. Aurora クラスター情報の確認

aws rds describe-db-clusters \
  --db-cluster-identifier "ypd-dev-aurora-main-cluster" \
  --region us-west-2 \
  --query 'DBClusters[0].{ClusterArn:DBClusterArn,DatabaseName:DatabaseName,MasterUsername:MasterUsername,HttpEndpointEnabled:HttpEndpointEnabled}'

出力例:

{
    "ClusterArn": "arn:aws:rds:us-west-2:123456789012:cluster:ypd-dev-aurora-main-cluster",
    "DatabaseName": "main_db",
    "MasterUsername": "ypodu_pdadmin",
    "HttpEndpointEnabled": true
}

1.2. Secrets Manager の認証情報ARN取得

aws secretsmanager list-secrets \
  --region us-west-2 \
  --query 'SecretList[?contains(Name, `rds`)].{Name:Name,ARN:ARN}'

出力例:

[
    {
        "Name": "rds!cluster-c8888888-d222-1c11-999c-445cc44444444",
        "ARN": "arn:aws:secretsmanager:us-west-2:123456789012:secret:rds!cluster-c8888888-d222-1c11-999c-445cc44444444-CMHOsq"
    }
]

2. Aurora PostgreSQL の初期設定（Data API）

DATA API(SQL を直接 HTTP 経由で実行できる API) を使用して Aurora PostgreSQL に必要な拡張機能とテーブルを作成します。
取得した ClusterArn と Secret ARN を使って、以下のリソースを作成します。以下のコマンドの
--resource-arn,
--secret-arn
は適宜置き換えてください。

2.1. pgvector 拡張の有効化

aws rds-data execute-statement \
  --resource-arn 'arn:aws:rds:us-west-2:123456789012:cluster:ypd-dev-aurora-main-cluster' \
  --secret-arn   'arn:aws:secretsmanager:us-west-2:123456789012:secret:rds!cluster-c8888888-d222-1c11-999c-445cc44444444-CMHOsq' \
  --database     'main_db' \
  --sql          'CREATE EXTENSION IF NOT EXISTS vector;' \
  --region       us-west-2

2.2. Bedrock Knowledge Base 用テーブルの作成

Titan V2 に対応するため、vector(1024) 型を使用します。

aws rds-data execute-statement \
  --resource-arn 'arn:aws:rds:us-west-2:123456789012:cluster:ypd-dev-aurora-main-cluster' \
  --secret-arn   'arn:aws:secretsmanager:us-west-2:123456789012:secret:rds!cluster-c8888888-d222-1c11-999c-445cc44444444-CMHOsq' \
  --database     "main_db" \
  --sql          "CREATE TABLE IF NOT EXISTS bedrock_knowledge_base (
                    id        UUID PRIMARY KEY DEFAULT gen_random_uuid(),
                    embedding vector(1024),
                    chunks    TEXT NOT NULL,
                    metadata  JSONB
                 );" \
  --region       us-west-2

2.3. テキスト検索用 GIN インデックスの作成

aws rds-data execute-statement \
  --resource-arn 'arn:aws:rds:us-west-2:123456789012:cluster:ypd-dev-aurora-main-cluster' \
  --secret-arn   'arn:aws:secretsmanager:us-west-2:123456789012:secret:rds!cluster-c8888888-d222-1c11-999c-445cc44444444-CMHOsq' \
  --database     'main_db' \
  --sql          'CREATE INDEX IF NOT EXISTS bedrock_knowledge_base_chunks_idx 
                    ON bedrock_knowledge_base USING gin 
                    (to_tsvector('\''simple'\'', chunks));' \
  --region       us-west-2

2.4. ベクター検索用 HNSW インデックスの作成

aws rds-data execute-statement \
  --resource-arn 'arn:aws:rds:us-west-2:123456789012:cluster:ypd-dev-aurora-main-cluster' \
  --secret-arn   'arn:aws:secretsmanager:us-west-2:123456789012:secret:rds!cluster-c8888888-d222-1c11-999c-445cc44444444-CMHOsq' \
  --database     'main_db' \
  --sql          'CREATE INDEX IF NOT EXISTS bedrock_knowledge_base_embedding_idx 
                    ON bedrock_knowledge_base USING hnsw 
                    (embedding vector_cosine_ops);' \
  --region       us-west-2

3. 作成内容の確認

3.1 テーブルの存在確認

aws rds-data execute-statement \
  --resource-arn 'arn:aws:rds:us-west-2:123456789012:cluster:ypd-dev-aurora-main-cluster' \
  --secret-arn 'arn:aws:secretsmanager:us-west-2:123456789012:secret:rds!cluster-c8888888-d222-1c11-999c-445cc44444444-CMHOsq' \
  --database 'main_db' \
  --sql 'SELECT table_name FROM information_schema.tables WHERE table_name = '\''bedrock_knowledge_base'\'';' \
  --region us-west-2

出力例

{
    "records": [
        [
            {
                "stringValue": "bedrock_knowledge_base"
            }
        ]
    ],
    "numberOfRecordsUpdated": 0
}

3.2 インデックスの確認

aws rds-data execute-statement \
  --resource-arn 'arn:aws:rds:us-west-2:123456789012:cluster:ypd-dev-aurora-main-cluster' \
  --secret-arn 'arn:aws:secretsmanager:us-west-2:123456789012:secret:rds!cluster-c8888888-d222-1c11-999c-445cc44444444-CMHOsq' \
  --database 'main_db' \
  --sql 'SELECT indexname, indexdef FROM pg_indexes WHERE tablename = '\''bedrock_knowledge_base'\'';' \
  --region us-west-2

出力例

{
    "records": [
        [
            {
                "stringValue": "bedrock_knowledge_base_pkey"
            },
            {
                "stringValue": "CREATE UNIQUE INDEX bedrock_knowledge_base_pkey ON public.bedrock_knowledge_base USING btree (id)"
            }
        ],
        [
            {
                "stringValue": "bedrock_knowledge_base_chunks_idx"
            },
            {
                "stringValue": "CREATE INDEX bedrock_knowledge_base_chunks_idx ON public.bedrock_knowledge_base USING gin (to_tsvector('simple'::regconfig, chunks))"
            }
        ],
        [
            {
                "stringValue": "bedrock_knowledge_base_embedding_idx"
            },
            {
                "stringValue": "CREATE INDEX bedrock_knowledge_base_embedding_idx ON public.bedrock_knowledge_base USING hnsw (embedding vector_cosine_ops)"
            }
        ]
    ]
}

Knowledge Base 用のベクターデータベース設定が完了したので、続いて Knowledge Base の設定を行います。

Model 有効化

Amazon Bedrock では、各種基盤モデル（Anthropic Claude、Amazon Titan、Amazon Nova など）を使用する前に、明示的にアクセス許可を有効化する必要があります。

本ハンズオンでは以下のモデルを使用します

Amazon Nova Pro: Knowledge Base のテスト用
Amazon Titan Text Embeddings V2: ベクトル埋め込み生成用（Knowledge Base で自動的に使用）

これらのモデルを利用可能にするため、Amazon プロバイダーのモデルアクセスを一括で有効化します

[ Amazon Bedrock ] -> [ モデルアクセス ]

※左メニューの下部にあるため、注意
[ 特定のモデルを有効にする ] or [ モデルアクセスを変更 ]をクリックする
※AWS アカウントに対して初めてモデルアクセスを有効にする際は [ 特定のモデルを有効にする ]が表示される

[ ▼ Amazon ] を選択 [ 次へ ] をクリック [ 送信 ] をクリック [ モデルアクセス ] ページで、Amazon 配下のモデルにアクセスが付与されていることを確認
※有効になっていない場合は、10分ほど待つ

Knowledge Base の作成

Amazon 系の基盤モデルへのアクセスが有効化されたので、続いて Terraform で Bedrock Knowledge Base を apply します。

plan 確認

terraform/environment/dev-ypd/default ディレクトリに移動

cd terraform/environment/dev-ypd/default

03_bedrock_knowledgebase.tf.bk を 03_bedrock_knowledgebase.tf にリネーム

$ mv 03_bedrock_knowledgebase.tf.bk 03_bedrock_knowledgebase.tf
$ ls 03_bedrock_knowledgebase.tf
03_bedrock_knowledgebase.tf

terrafom plan で Bedrock Knowledge Base が add されることを確認

terraform plan

成功時の出力例

Plan: 2 to add, 0 to change, 0 to destroy.

apply 実行

terraform apply を実行して Bedrock Knowledge Base を作成

terraform apply

成功時の出力例

Apply complete! Resources: 2 added, 0 changed, 0 destroyed.

Outputs:

bedrock_knowledge_base_arn = "arn:aws:bedrock:us-west-2:123456789012:knowledge-base/NNIDIDIDID"
bedrock_knowledge_base_id = "NNIDIDIDID"
bedrock_knowledge_base_name = "ypd-dev-knowledge-base"

ベクターDBが正常に稼働していれば apply は成功します。

Knowledge Base ID の取得

apply 完了時に出力される
bedrock_knowledge_base_id の値（例: "NNIDIDIDID"）
は、後続の作業で使用するため控えておいて下さい。

Knowledge Base 動作確認

Knowledge Base 用 S3バケットへデータアップロード

[ Amazon S3 ] -> [ バケット ] -> [ ypd-dev-knowledgebase-bucket-aaa999bb ]
[ ↑ アップロード ] をクリック doc/knowledge-base-data-source 配下の vinyl_record.xlsx をアップロードします。
アップロードされたことを確認

Knowledge Base データソースに同期実行します。

[ Amazon Bedrock ] -> [ ナレッジベース ] -> [ ypd-dev-knowledge-base ] をクリック

[ データソース ] -> [ ypd-dev-kb-src-s3 ] を選択し
[ ↻ 同期 ] をクリック

[ ナレッジベースをテスト ]をクリックし、Knowledge Base の RAG 検索の動作確認します。 [ モデルを選択 ] で Amazon Nova Pro を選択し [ 適用 ]をクリック [ 質問を入力 ] に質問を入力
質問例: 「レコードのリストはありますか?」など応答が返ってくることを確認