はじめに
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エージェント開発の基礎ハンズオン用レポジトリ
本ハンズオンは Linux 環境を前提に作成されていますが、Docker Desktopがインストールされた macOS でも実施可能です。ただし、一部のコマンドやパスの指定方法が異なる場合があります。
必要なツール
- Docker および Docker Compose v2.x
- Compose は公式手順であればオプションとしてインストールされています。
- Git
- VS Code
- Terraform
以下のいずれも AdministratorAccess 相当の権限を持つ必要があります。
- マネジメントコンソールへのアクセス権（UI操作用）
- Terraform ・ AWS CLI を使用するための API 認証情報（アクセスキー・シークレットキーなど）
Asana アカウント
参加者の前提スキル
- 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 を実行する前に、準備と確認を行います。
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 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/environment/dev-ypd/default/backend_dev-ypd.tf の bucket を CloudShell で作成したバケット名に修正して下さい。
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用の環境変数を設定して下さい。
本来、Terraform を実行する際に環境変数による認証情報の指定は非推奨ですが、本ハンズオンではセットアップを簡易にするため、この手順を採用します。
AWS 関連環境変数
Terraform 実行前に AWS CLI を実行し AWS 認証情報が設定されていること、 S3 バケット名が表示されることを確認して下さい。
$ 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 を実行します。
$ 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"
}
]
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 を選択し [ 適用 ]をクリック
[ 質問を入力 ] に質問を入力
質問例: 「レコードのリストはありますか?」など
応答が返ってくることを確認
Part 1 まとめ
ここまでで、Terraform を使用した AWS 環境の構築と、Amazon Bedrock Knowledge Base の初期設定が完了しました。
次回の Part 2 では、構築した環境を使用して、ローカルでコンテナを起動し、AI Agent が Asana MCP Server や Knowledge Base と実際に連携する様子を確認していきます。
