Managed Knowledge BaseとAgentCore Gatewayで既存ナレッジをAWS DevOps Agentに参照させてみた

こんにちは。クラウド事業統括本部コンサルティング1部の桑野です。

皆さんは DevOps Agent を使っていて、既存のドキュメントを参照させたいと感じたことはありませんか？
私はあります。

今回は Amazon Bedrock の Managed Knowledge Base と AgentCore Gateway を組み合わせて、既存ナレッジを DevOps Agent から参照できるようにする方法を共有します。

構成

今回の構成は以下のとおりです。

AgentCore Gateway は Knowledge Base をネイティブ統合しており、ターゲットとしてKnowledge Base を直接指定できます。ターゲットを作成すると Gateway 側が MCP ツールを自動的に生成してくれるため、エージェントはそれを呼ぶだけでナレッジを取得できます。

ドキュメントの検索基盤としては、埋め込みモデルとベクトルストアが Managed Knowledge Base 側で提供されます。ベクトルストアを自分で用意する必要もありません。

なお AgentCore Gateway 自体の作成手順については、以前マネジメントコンソールから作成する記事を書いていますので、Gateway をまだ作ったことがない方はこちらもご覧ください。

https://dev.classmethod.jp/articles/bedrock-agentcore-gateway-management-console/

動作確認の設計

今回の構成によって DevOps Agent が「ナレッジを参照できた」と言い切るためには、エージェントが KB を読まない限り絶対に答えられない問いを用意する必要があります。

AWSの一般的な知識で答えられてしまう問いだと、KBを引いたのか元々知っていたのか区別がつきません。そこで以下のようにユースケースを考えました。

• 架空の社内エラーコード体系（KWN-1001 など）をランブックとして KB に格納する
• Lambda からは エラーコードだけを CloudWatch Logs に出力する
• コードの意味や対処法はログに一切書かない

こうすると、ログを見ただけでは KWN-1001 が何を指すのかは分からないはずです。KB を参照して初めて意味にたどり着くことができます。

実際の運用でも「ログにはコードだけが記録され、意味は別ドキュメントで管理されている」というケースはあり得るかと思いますので、ユースケースとしても自然かなと考えています。

KB に格納したドキュメント

検証の際は以下のmarkdownファイルを使用しています。

1. 架空の社内ランブック

# 社内インシデント対応ランブック（KWNエラーコード体系）

本書は架空の社内システム「KWNプラットフォーム」における、エラーコード別の初動対応・恒久対策・エスカレーション基準を定めたランブックである。オンコール担当者は、CloudWatch Logsやアラート上で該当エラーコードを確認した場合、本書の記載に従って対応すること。

## 1. エラーコード対応表

| エラーコード | 概要 | 一次対応 |
|---|---|---|
| KWN-1001 | 決済APIのタイムアウト | 5分待って再送。復旧しなければ決済チームへエスカレーション |
| KWN-2003 | 在庫同期の不整合 | 在庫同期バッチを手動再実行 |
| KWN-3007 | 認証トークンの期限切れ | トークン再発行バッチを実行 |

以降、各コードの詳細を記載する。

---

## 2. KWN-1001: 決済APIのタイムアウト

### 発生原因
決済基盤（社内コードネーム「銭亀ゲートウェイ」）への接続で、下流の決済プロセッサからの応答が社内標準タイムアウト値（8秒）を超えた場合に発生する。深夜バッチによる決済基盤側のインデックス再構築ジョブが稼働している時間帯（毎週水曜2:00〜3:30）は発生率が上昇する傾向がある。

### 一次対応
1. まず該当リクエストを5分待機してから再送する。決済基盤側の一時的な混雑であれば、この待機で自然復旧するケースが大半である。
2. 5分後の再送でも同一エラーが返る場合、決済チーム（Payment-Guild）へエスカレーションする。エスカレーション時は下記情報を添えること。
   - 発生時刻（分単位）
   - リクエストID（requestId）
   - 直近30分間の発生回数
3. 決済チームのオンコールは `#kwn-payment-oncall` チャンネルに常駐している想定で連絡する。

### 恒久対策
- 決済プロセッサ側のSLA見直し交渉（四半期ごとに基盤チームと決済チームが合同レビューを実施）。
- タイムアウト値そのものの調整は基盤チームの承認が必須（安易な延長はユーザー体験悪化につながるため）。

### 再発時の見分け方
同一 `requestId` プレフィックス（先頭8桁）で短時間に連続発生する場合は、特定の決済プロセッサ経路（例: 経路コードP2)に偏っている可能性がある。経路コード別の発生分布を集計し、偏りがあれば決済チームへの報告時に経路コードを明記する。

---

## 3. KWN-2003: 在庫同期の不整合

### 発生原因
店舗系在庫管理サブシステム（社内コードネーム「蔵番」）と中央在庫DBの間で行われる差分同期処理において、同期対象レコードのバージョン番号が中央側より古い状態で送信された場合に発生する。主な引き起こし要因は以下の3点。
- 店舗側ネットワークの一時的な遅延により、複数世代の差分が入れ子で送信された。
- 在庫棚卸バッチと通常同期処理が同時間帯に競合した。
- 店舗コードの入力ミスにより、存在しない店舗宛の差分が送信された。

### 一次対応
1. 在庫同期バッチ（`inventory-sync-batch`）を手動で再実行する。再実行は在庫チームの管理コンソールから「同期リトライ」ボタンで行う。
2. 再実行後も不整合が解消しない場合は、対象店舗コードを在庫チーム（Stock-Watch）へ連絡し、対象店舗のみ同期対象から一時除外する。
3. 深夜帯（23:00〜6:00）に発生したKWN-2003については、原則として即時対応は不要であり、**翌営業日の対応で問題ない**。これは深夜帯の在庫変動が業務影響として軽微であるという過去の運用実績に基づく判断である。ただし、対象店舗が「重要拠点フラグ」を持つ場合はこの例外は適用されず、通常対応（即時対応）とする。

### 恒久対策
- 店舗側同期エージェントのバージョンアップ（世代混在を防ぐシーケンス制御の導入）。
- 棚卸バッチと同期処理のスケジュール分離（在庫チームが四半期ごとに見直し）。

### 再発時の見分け方
同一店舗コードから短間隔（10分以内）で3回以上発生する場合は、店舗側エージェントの再起動が必要な兆候である。単発かつ深夜帯であれば通常は自然解消するケースが多い。

---

## 4. KWN-3007: 認証トークンの期限切れ

### 発生原因
社内認証基盤（社内コードネーム「鍵守」）が発行するアクセストークンの有効期限（標準45分）が切れた状態で、後続処理からAPIコールが行われた場合に発生する。トークン更新処理（リフレッシュ）が何らかの理由で失敗し、古いトークンが使い続けられているケースが典型的である。

### 一次対応
1. トークン再発行バッチ（`token-reissue-batch`）を実行する。実行権限は基盤チーム（Foundation-Ops）および各サービスチームのオンコール担当者に付与されている。
2. 再発行後、対象サービスの処理が正常に再開されたことを確認する。
3. 再発行バッチ自体が失敗する場合は、鍵守基盤の障害を疑い、基盤チームへ即時エスカレーションする（このケースはKWN-3007としての一次対応範囲を超える）。

### 恒久対策
- リフレッシュ処理の失敗検知とアラート連携の強化（現状はサイレント失敗するケースがあるため、基盤チームが監視強化を計画中）。
- トークン有効期限の延長は原則行わない（セキュリティポリシー上、45分が下限かつ推奨値）。

### 再発時の見分け方
特定サービスからのみ繰り返しKWN-3007が発生する場合は、そのサービスのリフレッシュ処理実装に固有の不具合がある可能性が高く、単純な再発行バッチの実行では解消しない。この場合は基盤チームに実装レベルの調査を依頼する。

---

## 5. エスカレーション基準まとめ

| 条件 | エスカレーション先・対応方針 |
|---|---|
| KWN-1001 が10分以内に3回以上発生 | レベル2エスカレーション（決済チームの責任者クラスへ直接連絡） |
| KWN-2003 が深夜帯（23:00〜6:00）に発生（重要拠点フラグなし） | 翌営業日対応で可。即時対応は不要 |
| KWN-2003 が重要拠点フラグ付き店舗で発生 | 深夜帯であっても即時対応 |
| KWN-3007 の再発行バッチ自体が失敗 | 基盤チームへ即時エスカレーション |
| 上記以外で15分以内に自己解決しない場合 | 基盤チーム経由で該当サービスチームへ連絡 |

## 6. 関連チーム一覧

| チーム名 | 役割 |
|---|---|
| 決済チーム（Payment-Guild） | 決済API・決済プロセッサ連携の運用 |
| 在庫チーム（Stock-Watch） | 在庫同期・棚卸バッチの運用 |
| 基盤チーム（Foundation-Ops） | 認証基盤・共通インフラの運用 |
| SRE当直（KWN-SRE-OnCall） | 全体監視・一次切り分け・エスカレーション判断 |

以上。本ランブックは社内Wiki「KWN Runbook Space」の抜粋版であり、詳細な手順書へのリンクは社内ネットワークからのみ参照可能。

2. リソースの命名規則とタグポリシー

# AWSリソース命名規則・タグポリシー（社内標準）

本書は架空の社内標準「KWNクラウド運用ガイドライン」より、AWSリソースの命名規則とタグポリシーの抜粋である。すべてのリソースは本規則に従って作成すること。

## 1. 環境識別子

| 識別子 | 環境 |
|---|---|
| `prd` | 本番環境 |
| `stg` | ステージング環境 |
| `dev` | 開発環境 |

環境識別子は必ずリソース名の先頭に置く。

## 2. Lambda関数の命名規則

```
{env}-{service}-{機能}-fn
```

- `env`: 上記の環境識別子（prd / stg / dev）
- `service`: サービス名（例: payment, inventory, auth）
- `機能`: 関数が担う機能を表す短い英語（例: refund, sync, reissue）
- 末尾は必ず `-fn` サフィックスを付与する

### 例
- `prd-payment-refund-fn`（本番・決済サービス・返金処理）
- `stg-inventory-sync-fn`（ステージング・在庫サービス・同期処理）
- `dev-auth-reissue-fn`（開発・認証サービス・トークン再発行処理）

## 3. S3バケットの命名規則

```
kwn-{env}-{service}-{用途}
```

- 全体で小文字・ハイフンのみを使用する（S3バケット名の制約に準拠）
- `用途`: バケットの用途を表す短い英語（例: logs, artifacts, docs, backup）

### 例
- `kwn-prd-payment-logs`
- `kwn-stg-knowledge-docs`
- `kwn-dev-inventory-backup`

## 4. DynamoDBテーブルの命名規則

```
{env}-{service}-{エンティティ名}-tbl
```

- `エンティティ名`: 単数形の英語を使用する（例: order, token, item）
- 末尾は必ず `-tbl` サフィックスを付与する

### 例
- `prd-payment-order-tbl`
- `stg-auth-token-tbl`
- `dev-inventory-item-tbl`

## 5. 必須タグポリシー

すべてのAWSリソースには、作成時に以下3つのタグを必ず付与する。タグ欠落があるリソースは、月次のコスト・資産棚卸で「非準拠リソース」として報告対象となる。

| タグキー | 内容 | 形式・許容値 |
|---|---|---|
| `Owner` | 運用責任を持つチーム名 | 例: payment-guild, stock-watch, foundation-ops |
| `CostCenter` | コスト配賦先のコストセンターコード | `CC-` + 6桁の数字（例: `CC-123456`） |
| `Criticality` | リソースの重要度 | `high` / `medium` / `low` のいずれか |

### タグ付与例（Lambda関数）

```
Owner=payment-guild
CostCenter=CC-482910
Criticality=high
```

## 6. Criticality = high リソースの変更運用ルール

`Criticality` タグが `high` に設定されているリソースに対する変更（設定変更・コード更新・削除等）は、以下のプロセスを必須とする。

1. 変更内容を「変更管理チケット」として起票する。
2. 基盤チーム（Foundation-Ops）のレビュー担当者による事前承認を得る。
3. 承認が得られるまで、本番環境への変更適用（デプロイ）を実施してはならない。
4. 緊急障害対応など承認を待てない場合は、SRE当直（KWN-SRE-OnCall）の口頭承認をもって仮承認とし、事後24時間以内に正式な変更管理チケットを起票する。

`Criticality` が `medium` および `low` のリソースについては、上記の事前承認プロセスは不要であるが、変更ログの記録は必須とする。

## 7. 命名規則違反時の扱い

命名規則に準拠していないリソースが検出された場合、以下の対応を行う。

- 新規作成分: 作成者に即時修正を依頼する（リソースの再作成を含む）。
- 既存リソース: 月次棚卸で一覧化し、影響範囲を確認した上で計画的にリネーム、またはタグの追加を行う。稼働中の本番リソース（`Criticality=high`）のリネームは、上記6章の事前承認プロセスに従う。

以上。

これらはすべて完全な架空の内容です。実在する規約ではないので、エージェントが正しく答えられればKBを参照したと言えるでしょう。

検証用の Lambda

エラーコードだけを出力する Lambda を用意しました。

import logging
import uuid

logger = logging.getLogger()
logger.setLevel(logging.INFO)

_LOG_MESSAGE_TEMPLATES = {
    "KWN-1001": "code=KWN-1001 requestId=%s",
    "KWN-2003": "code=KWN-2003 requestId=%s",
    "KWN-3007": "code=KWN-3007 requestId=%s",
}

_DEFAULT_CODE = "KWN-1001"

def lambda_handler(event, context):
    event = event or {}
    code = event.get("code", _DEFAULT_CODE)
    request_id = str(uuid.uuid4())

    if code in _LOG_MESSAGE_TEMPLATES:
        logger.error(_LOG_MESSAGE_TEMPLATES[code], request_id)

    return {"statusCode": 200, "body": {"code": code, "requestId": request_id}}

ポイントは、ログに timeout や expired といった意味を推測させる英単語を一切含めていないところです。出力されるのは code=KWN-1001 requestId=xxx だけになります。

この Lambda はあくまで 調査対象のダミーアプリケーションであり、KB へのアクセス経路には一切関与しません。この点は混同しやすいので補足しておきます。
デプロイした後、動作確認前にテスト実行しておきましょう。

始める前に

以下を確認してください。

• 対象 AWS アカウントのマネジメントコンソールにサインインできること
• Amazon Bedrock、Amazon Bedrock AgentCore、Amazon S3、IAM を操作できる IAM 権限があること
• Knowledge Base に格納するドキュメント（Markdown、PDF、テキストなど）が手元にあること

構築手順

依存関係の都合上、以下の順序で作業を進めます。

作業中につまずいた場合は、末尾の「トラブルシューティング」を参照してください。

Agent Space を作成する

ステップ 1: DevOps Agent コンソールを開く

1. AWS マネジメントコンソールで AWS DevOps エージェント を検索して開きます
2. トップページの セットアップを開始 をクリックします

ステップ 2: Agent Space の詳細を入力する

「エージェントスペースを作成」画面が開いている状態です。

1. エージェントスペース名 を入力します（例: my-dev-poc-agent-space）
2. 説明 を入力します（オプション）
   ※改行するとエラーになるため、1行で記載すると良いです。
3. エージェントの応答言語 を選択します（例: 日本語 (Japan)）

ステップ 3: プライマリアカウントのアクセス権限を設定する

「この Agent Space AWS リソースへのアクセスを許可する」セクションで IAM ロールを設定します。

1. 新しい DevOps エージェントロールを自動作成 を選択します（推奨）
   • 既存のロールを使う場合は「既存のロールを割り当て」を選択し、ロール名を入力します
   • ポリシーテンプレートから手動で作成する場合は「ポリシーテンプレートを使用して新しい DevOps エージェントロールを作成」を選択します
2. 作成される エージェントスペースロール名 を確認します（自動生成されていますが、変更可能です）

ステップ 2 ~ 3 の設定を反映すると以下のようになります。

ステップ 4: タグの設定を行う

アカウントやプロジェクトでタグのルールがなければ設定不要です。

1. 新しいタグを追加 をクリックします
2. Key と Value をそれぞれ入力します

ステップ 5: Agent Space へのウェブアプリアクセスを有効にする

「ウェブアプリを有効にする」セクションで IAM ロールを設定します。

1. 新しい DevOps エージェントロールを自動作成 を選択します（推奨）
   • 既存のロールを使う場合は「既存のロールを割り当て」を選択し、ロール名を入力します
   • ポリシーテンプレートから手動で作成する場合は「ポリシーテンプレートを使用して新しい DevOps エージェントロールを作成」を選択します
2. 作成される ウェブアプリロール名 を確認します（自動生成されていますが、変更可能です）

ステップ 6: 暗号化キーを設定する

「詳細設定」セクションで Agent Space の詳細情報、DevOps Agent Web App 上で作成されたコンテンツの暗号化に使用するキーを設定します。

1. 暗号化キータイプで AWS が所有するキー を選択します
   ※独自 KMS キーを使用する必要がある場合は 顧客管理キー を選択します

ステップ 4 ~ 6 の設定を反映すると以下のようになります。

ここまでの手順が完了したら、作成 をクリックします。

ステップ 7: 作成完了を確認する

「Agent Space created successfully」のバナーが表示されれば作成完了です。
Agent Space のトップページが開き、エージェントのマッピングが開始されます。

このあとの手順で MCP サーバーを登録するため、Agent Space の ARN を控えておきます。IAM ロールの信頼ポリシーで使用します。

S3 バケットを作成してドキュメントをアップロードする

Knowledge Base のデータソースとなる S3 バケットを準備します。

ステップ 1: バケットを作成する

1. Amazon S3 のコンソールを開き、バケットを作成 をクリックします
2. AWS リージョン で アジアパシフィック (東京) ap-northeast-1 を選択します
3. バケット名 を入力します（例: kuwano-dev-poc-bucket-for-knowledge-base）
4. バケットタイプ、オブジェクト所有者はいずれも既定値のまま バケットを作成 をクリックします

ステップ 2: ドキュメントをアップロードする

1. 作成したバケットを開き、アップロード をクリックします
2. ファイルを追加 または フォルダの追加 から、Knowledge Base に格納するドキュメントを指定します
3. アップロード をクリックします

本手順では samples/ プレフィックス配下に runbook.md（社内ランブック）と naming-convention.md（命名規則・タグポリシー）の2ファイルを配置しています。

プレフィックスの有無はどちらでも構いません。後続のデータソース設定でバケット直下を指定した場合、プレフィックス配下のファイルも再帰的にクロールされます。

Managed Knowledge Base を作成する

ドキュメントを検索可能にするための Knowledge Base を作成します。

ステップ 1: ナレッジベースの一覧を開く

1. Amazon Bedrock のコンソールを開きます
2. 左サイドメニューの 構築 から ナレッジベース を選択します

ステップ 2: Managed KB の作成を開始する

1. Create Managed KB をクリックします

ステップ 3: 基本情報とデータソースを入力する

作成画面を開いた直後は、ナレッジベース名とデータソース名に knowledge-base-quick-start-xxxxx のような値が自動採番されています。

1. ナレッジベース名 を自分の命名規則に沿った値に変更します（例: kuwano-dev-poc-knowledge-base-for-devops-agent）
2. データソース名 は自動採番された値のままで構いません
3. Data source type で Amazon S3 を選択します
4. データソースの場所 で この AWS アカウント を選択します
5. S3 の URI に、S3 バケット作成手順で用意したバケットを指定します（例: s3://kuwano-dev-poc-bucket-for-knowledge-base）

ステップ 4: オプションを設定して作成する

1. 必要に応じて画面下部のオプションを設定します
2. ナレッジベースを作成 をクリックします

ステップ 5: 作成完了を確認する

作成が完了すると Knowledge Base の詳細画面に遷移します。

以下を確認します。

この時点ではデータソースが 0 件の表示になっています。次の章で同期を実行すると反映されます。

画面右上に Use with AgentCore Gateway ボタンがあります。ここから Gateway 作成に進むこともできます。

データソースを同期する

S3 にファイルを配置しただけでは、Knowledge Base はドキュメントを検索できません。同期（Sync）を実行してベクトル化する必要があります。

ステップ 1: 同期を実行する

1. Knowledge Base 詳細画面の データソース セクションで、対象のデータソースを選択します
2. 同期 をクリックします

同期が完了すると、成功バナーが表示されます。

以下を確認します。

同期完了後、ベクトル埋め込みが反映されるまで数分かかる場合があります。
気長に待ちましょう。

ステップ 2: 検索できるか確認する

1. ナレッジベースをテスト をクリックします
2. 格納したドキュメントの内容について検索し、意図した結果が返るか確認します

ここで検索できない場合、後続の Gateway 設定に進んでも解決しません。先に Knowledge Base 側を解決してください。

AgentCore Gateway を作成する

Knowledge Base を MCP ツールとして公開する Gateway を作成します。

ステップ 1: ゲートウェイの作成を開始する

1. Amazon Bedrock AgentCore のコンソールを開きます
2. 左サイドメニューの 構築 から ゲートウェイ を選択します
3. ゲートウェイを作成 をクリックします

ステップ 2: ゲートウェイの詳細とインバウンド認証を設定する

1. ゲートウェイ名 を入力します（例: kuwano-dev-poc-agentcore-gateway）
2. Inbound Auth type で IAM 許可を使用 を選択します

Inbound Auth type の選択肢は以下の3つです。ここで選んだ方式は、後続の DevOps Agent 側の認証設定と一致させる必要があります。

ステップ 3: Permissions で IAM ロールを設定する

1. IAM アクセス許可 で デフォルトロールを作成 を選択します
   ※ Gateway 用のサービスロールが自動生成されます。Role name は自動採番されます

ステップ 4: ターゲットのプロトコルを選択する

1. Target protocol で MCP target を選択します

選択肢は以下のとおりです。

ステップ 5: ターゲットに Knowledge Base を指定する

1. ターゲット名 を入力します（例: managed-kb）
   ※ 50文字以内。短く付けてください（理由は下記）
2. 実行時取得タイプ で 標準検索 を選択します
3. ナレッジベース（KB） で、作成済みの Knowledge Base をドロップダウンから選択します
4. アウトバウンド認証設定 で IAM ロール を選択します
   ※ Gateway のサービスロールで KB を参照します
5. ツールの説明 は任意です
   ※ エージェントがツールを選択する判断材料になります

実行時取得タイプには2つの選択肢があります。

ステップ 6: ゲートウェイリソース URL を控える

1. ゲートウェイを作成 をクリックします
2. 作成された Gateway の詳細画面で ゲートウェイリソース URL をコピーします

末尾の /mcp まで含めた完全な URL を控えておきます。MCP サーバー登録時に使用します。あわせて ゲートウェイリソース ARN も控えておきます。IAM ロールのポリシーで使用します。

以下を確認します。

IAM ロールを作成する

DevOps Agent が Gateway を呼び出す際に使用する IAM ロールを作成します。

このロールは、後続の MCP サーバー登録画面で「ポリシーテンプレートを使用して新しい DevOps エージェントロールを作成」を選ぶと、必要な信頼ポリシーと作成手順が画面に表示されます。事前に用意しない場合はそちらを使っても構いません。

ステップ 1: カスタム信頼ポリシーでロールを作成する

1. IAM コンソールで ロールを作成 を開きます
2. カスタム信頼ポリシー を選択します
3. 以下の信頼ポリシーを入力します

{
  "Version": "2012-10-17",
  "Statement": [
    {
      "Effect": "Allow",
      "Principal": {
        "Service": "aidevops.amazonaws.com"
      },
      "Action": "sts:AssumeRole",
      "Condition": {
        "StringEquals": {
          "aws:SourceAccount": "アカウントID"
        },
        "ArnLike": {
          "aws:SourceArn": "エージェントスペースのARN/*"
        }
      }
    }
  ]
}

サービスプリンシパルは aidevops.amazonaws.com です。aws:SourceArn には Agent Space 作成時に控えた ARN を指定します。

ステップ 2: Gateway を呼び出す権限を付与する

1. インラインポリシーを作成 を選択します
2. 以下のポリシーを入力します

{
  "Version": "2012-10-17",
  "Statement": [
    {
      "Effect": "Allow",
      "Action": "bedrock-agentcore:InvokeGateway",
      "Resource": "ゲートウェイリソース ARN"
    }
  ]
}

Resource には Gateway 詳細画面で控えた「ゲートウェイリソース ARN」を指定します。

ステップ 3: ロール名を入力して作成する

1. ロール名 を入力します（例: DevOpsAgentRole-Service-AgentCore-Gateway）
2. ロールを作成 をクリックします

DevOps Agent に MCP サーバーとして登録する

作成した Gateway を DevOps Agent から呼び出せるようにします。

ステップ 1: MCP サーバーの登録を開始する

1. AWS DevOps Agent のコンソールを開き、対象のエージェントスペースを選択します
2. MCP サーバー セクションの 追加 をクリックします
3. 「機能を追加」ダイアログで 新しい MCP サーバーの登録 の 登録 をクリックします

ステップ 2: MCP サーバーの詳細を入力する

1. 名前 を入力します（例: kuwano-dev-poc-knowledge-base）
   ※ ツール名との合計が 64 文字以内である必要があります
2. エンドポイント URL に、Gateway 詳細画面で控えた URL を入力します
3. 説明 を任意で入力します
4. 動的クライアント登録を有効化 のチェックを外します
5. プライベート接続を使用してエンドポイントに接続 のチェックを外します

詳細設定 を展開すると暗号化キータイプを選択できます。既定の AWS が所有するキー であれば追加設定は不要です。

ステップ 3: 認証フローを選択する

1. 認証フローで AWS SigV4 を選択します

選択肢は以下のとおりです。

Gateway のインバウンド認証を IAM にしているため、ここでは AWS SigV4 を選択します。

ステップ 4: 認証設定を入力する

1. IAM ロールを設定 で 既存のロールを割り当て を選択し、IAM ロール作成手順で用意したロールを指定します
2. AWS リージョン に ap-northeast-1 を入力します
3. サービス名 に bedrock-agentcore を入力します

IAM ロールを事前に作成していない場合は、ポリシーテンプレートを使用して新しい DevOps エージェントロールを作成 を選択します。ロール名を入力すると、必要な信頼ポリシーと作成手順が画面に表示されます。

表示される手順は以下の4ステップです。この内容に沿って IAM コンソールでロールを作成すれば、「IAM ロールを作成する」と同じ結果になります。

ステップ 5: 内容を確認して登録する

1. レビュー画面で入力内容を確認します
2. 追加 をクリックします

ステップ 6: 使用するツールを選択する

1. 「MCP サーバーツールを選択」画面で managed-kb___Retrieve にチェックを入れます
2. 保存 をクリックします

ステップ 7: 関連付けを確認する

MCP サーバーが関連付けられたことを確認します。

ツール列が 1 個が利用可能 / 1 個が接続済み になっていれば成功です。

動作確認

DevOps Agent のチャットから、Knowledge Base の内容を参照できるか確認します。

チャット画面へのアクセス方法は、Agent Space の ウェブアプリ タブから IAM 経由で起動する をクリックします。

ナレッジベースの内容を直接聞く

Knowledge Base に格納した内容について質問します。

KWN-1001 というエラーコードの意味と、発生時の一次対応を教えてください。

「ナレッジベースを確認します」という前置きのあと、「社内ランブックから情報が見つかりました！」として、Knowledge Base に格納した内容に基づいた回答が返れば成功です。

回答の途中にある「1 個のツール 使用済み」を展開すると、managed-kb___Retrieve が呼ばれていることを確認できます。

実リソースの調査と組み合わせる

実リソースの調査と組み合わせた質問を投げます。

Lambda関数 <関数名> でエラーが発生しています。
CloudWatch Logs を調査して、原因と対応方法を教えてください。

エージェントが Investigation を起票し、CloudWatch Logs の分析を進めます。ログにエラーコードのみが記録されている場合、その意味は Knowledge Base を参照しない限り分かりません。ランブックの対応手順が回答に含まれていれば、ログ調査と Knowledge Base 参照の複合動作ができています。

別のドキュメントも参照できるか確認する

Knowledge Base の別のドキュメントも参照できるか確認します。

このアカウントの ap-northeast-1 にある Lambda 関数が、
社内の命名規則とタグポリシーに準拠しているか確認してください。

Knowledge Base に格納した命名規則・タグポリシーと、実際の AWS リソースを突き合わせた判定が返れば成功です。

検証が終わったあと、今回構築したリソースが必要なければ、しっかりと削除しておきましょう。

トラブルシューティング

実際に検証する中で踏んだハマりどころをまとめます。

質問しても「情報が見つかりませんでした」と返る

原因: データソースの同期が未実行、またはベクトル埋め込みの反映待ち。

S3 にファイルを配置してデータソースを登録しただけでは、Knowledge Base は中身を認識しません。同期が済んでいない状態で質問すると、以下のような回答が返ります。

ナレッジベースには KWN-1001 に関する情報が見つかりませんでした。
残念ながら、KWN-1001 というエラーコードについての情報は、
現在このエージェントスペースのナレッジベースに登録されていません。

エラーではなく通常の回答として返るため、原因に気づきにくい点が厄介です。「ナレッジベースへの登録」を提案してくる場合もありますが、実際にはドキュメントを配置済みで同期だけが漏れている状態です。

対処: 「データソースを同期する」の同期を実行します。同期後もベクトル埋め込みの反映に数分かかる場合があるため、少し待ってから再試行してください。

同期を実行したうえで同じ質問を投げると、正しく回答が返るようになります。

データソースが 0 件のまま表示される

原因: データソースの作成が完了していない。

Knowledge Base 作成時に S3 の URI を指定していても、データソースセクションが「データソース (0)」「データソースなし」と表示されることがあります。

Managed Knowledge Base のデータソース作成は非同期処理で、ステータスが CREATING から AVAILABLE に変わるまで2〜5分かかります。この間に画面を離れると、作成が中断されたように見えることがあります。

対処: まずステータスが AVAILABLE になるまで待ちます。それでも 0 件のままであれば、追加 ボタンからデータソースを登録し直してください。

1. データソース名 は自動採番された値のままで構いません
2. Data source type で Amazon S3 を選択します
3. データソースの場所 で この AWS アカウント を選択します
4. S3 の URI にドキュメントを配置したバケットを指定します

このとき S3 の URI にプレフィックスを含めるかどうかで挙動が変わります。

samples/ 配下にファイルを置いている場合、どちらの指定でもファイルは取り込まれます。バケット内が検証用ファイルだけであれば、バケット直下の指定で問題ありません。特定のプレフィックスだけを対象にしたい場合はプレフィックス付きで指定してください。

データソースを追加したら、あらためて同期を実行します。

MCP サーバー登録時に64文字超過エラーが出る

原因: 「MCP サーバー名 + ツール名」の合計が 64 文字を超えている。

Gateway のターゲット名が長い場合に発生します。クイックスタートで Gateway を作成すると target-quick-start-d09925 のような長い名前が自動採番され、この制限に引っかかります。

The combination of MCP Server name and tool
(kuwano-dev-poc-knowledge-base_target-quick-start-d09925___Retrieve)
exceeds the maximum allowed length of 64 characters.
Please shorten the name or tool name.

内訳は以下のとおりです。

kuwano-dev-poc-knowledge-base_target-quick-start-d09925___Retrieve
└─────── 29文字 ───────┘ └──────────── 36文字 ────────────┘
合計 66文字 → 上限を2文字超過

対処: 以下のいずれかで解消します。

なお MCP サーバーの登録自体は成功しており、失敗しているのはツールの関連付けです。エラー画面でも「MCP サーバーが正常に登録されました」というバナーが先に表示されます。

SigV4 認証が通らない

原因: サービス名の指定ミス。

入力欄のプレースホルダーが execute-api になっているため、そのまま入力してしまうと署名検証に失敗します。

対処: サービス名に bedrock-agentcore を指定します。

まとめ

Managed Knowledge Base と AgentCore Gateway のネイティブ統合を使うことで、既存ナレッジを DevOps Agent から参照できるようになりました。管理するリソースが少ないため、ナレッジの中身を育てることに集中できそうです。

一方で、KB に何を入れるかは相応に考える必要がありそうです。今回は架空のランブックと命名規則を入れましたが、実際の運用では「エージェントに何を知っていてほしいか」を整理するところが本番になるかと思います。

エラーコードの意味、独自の運用ルール、過去のインシデント記録など、この辺のドキュメントが整理されているチームであれば、そのまま KB に載せるだけで DevOps Agent の調査精度が上がるはずです。逆に言うと、ドキュメントが整備されていない状態では効果が出にくいかもしれません。

この記事がどなたかの役に立てば幸いです。
最後までご覧いただきありがとうございました。

参考情報

https://docs.aws.amazon.com/bedrock-agentcore/latest/devguide/gateway.html

https://docs.aws.amazon.com/bedrock/latest/userguide/kb-data-source-sync-ingest.html

https://docs.aws.amazon.com/bedrock/latest/userguide/s3-data-source-connector.html

https://docs.aws.amazon.com/devopsagent/latest/userguide/configuring-integrations-and-knowledge-connecting-mcp-servers.html

https://aws.amazon.com/blogs/machine-learning/build-enterprise-search-for-agents-with-amazon-bedrock-managed-knowledge-base/