Smithyがすごい！AgentCoreゲートウェイとBedrockナレッジベースが直接つながる！！（LambdaやAgentCoreランタイムいらない）

三行まとめ

• SmithyはAWSのAPIを定義する言語
• AgentCoreゲートウェイにSmithyを使用するとAWS APIを呼び出すMCPサーバーが簡単に作れる
• Smityの定義を自分で記述するのは大変なので、Claudeに任せよう

AgentCoreゲートウェイのマネジメントコンソールにいるこいつ。
ずっと気になってたけど、見て見ぬふりしてたこいつ。

Smithy
スミシー？

だれ？

公式サイトがありました。
https://smithy.io/index.html

Chromeで翻訳してみました。

サービスを構築する。
SDKをビルドする。
Smithyで建築しよう。
サービスのモデリングは、インターフェースの種類に関わらず容易であるべきです。Smithyは拡張性、型安全性、プロトコル非依存性を備え、AWSのサービスを支えています。

わかったようなわからんような。。

AgentCoreゲートウェイの説明も日本語にしてみました。

Smithyモデルを使用してAPIインターフェースを定義し、MCP互換ツールを生成します。Smithyは、AWSサービスで使用できるサービスとSDKを定義するための言語です。ゲートウェイはSmithyモデルを使用して、AWSサービスまたはカスタムAPIと連携するツールを生成できます。

AWS SDKの定義に使用する言語だそうです。

細かいことはわからないですが、やってみよう！

読み物としては全然伝わらないと思いますが、ぜひ、手を動かしてみてください！

やってみる

自力では太刀打ちできなさそうなので、Claude Codeに任せましょう。

まずドキュメントを取得します。

curlを使って以下のファイルを取得し、docsディレクトリに配置してください。

Bedrock
https://docs.aws.amazon.com/bedrock/latest/userguide/llms.txt

Bedrock API
https://docs.aws.amazon.com/bedrock/latest/APIReference/llms.txt

AgentCore
https://docs.aws.amazon.com/bedrock-agentcore/latest/devguide/llms.txt

AgentCore Data Plane API
https://docs.aws.amazon.com/bedrock-agentcore/latest/APIReference/llms.txt

AgentCore Control Plane API reference
https://docs.aws.amazon.com/bedrock-agentcore-control/latest/APIReference/llms.txt


取得したファイルは、今後必要に応じて参照してください。

いつの頃からか、AWSのドキュメントがMarkdownで取得できます。
llms.txtも用意されています。素敵。

続いてナレッジベースを作りましょう。

東京リージョンに、Bedrockナレッジベースを作成してください。

- S3バケットをデータソースとする（S3バケットも新規作成）
- S3Vectorsをベクトルストアにする
- ベクトルモデルはTitan Text Embedding V2を使う
- docsディレクトリ内のファイルをS3に格納する

作成できたら、同期してください。

できました。（かしこい！）

本当にできたか、検索してみましょう。

作成したナレッジベースに対して、「AgentCore」で検索を行ってください。

結果が取得できました！

実行コマンドもいい感じです。ドキュメント渡してるからでしょうか。

aws bedrock-agent-runtime retrieve \
    --region ap-northeast-1 \
    --knowledge-base-id XN8VXHHA5T \
    --retrieval-query '{"text": "AgentCore"}' \
    --retrieval-configuration '{"vectorSearchConfiguration":{"numberOfResults":5}}' \
    --output json 2>&1 | python3 -c "

ここでいよいよSmithyの出番です。

Smithyのスキーマは、ここで公開されています。
https://github.com/aws/api-models-aws

今回はBedrockナレッジベース呼び出しに使う「retrieve」APIが含まれる「bedrock-agent-runtime」のスキーマを提示しました。1ファイルに全APIの定義が含まれてそうです。

AgentCoreゲートウェイのSmithyターゲットで、作成したナレッジベースに対して検索ができるようにしてください。

- インバウンド認証はIAM認証としてください。
- ツールのパラメーターは、最低限のもの（ナレッジベースIDや検索クエリなど）のみにしてください。
- Smithyスキーマはこれをダウンロードし、必要なスキーマを生成してください。
  https://github.com/aws/api-models-aws/blob/main/models/bedrock-agent-runtime/service/2023-07-26/bedrock-agent-runtime-2023-07-26.json

試行錯誤が数回ありますが、うまくできました！

作成したSmithyのスキーマはこんな感じでした。

手でかける気はしませんが、なんとなく読める感じですね。

{
  "smithy": "2.0",
  "shapes": {
    "com.amazonaws.bedrockagentruntime#AmazonBedrockAgentRunTimeService": {
      "type": "service",
      "version": "2023-07-26",
      "operations": [
        {
          "target": "com.amazonaws.bedrockagentruntime#Retrieve"
        }
      ],
      "traits": {
        "aws.api#service": {
          "sdkId": "Bedrock Agent Runtime",
          "arnNamespace": "bedrock",
          "endpointPrefix": "bedrock-agent-runtime"
        },
        "aws.auth#sigv4": {
          "name": "bedrock"
        },
        "aws.protocols#restJson1": {}
      }
    },
    "com.amazonaws.bedrockagentruntime#Retrieve": {
      "type": "operation",
      "input": {
        "target": "com.amazonaws.bedrockagentruntime#RetrieveRequest"
      },
      "output": {
        "target": "com.amazonaws.bedrockagentruntime#RetrieveResponse"
      },
      "traits": {
        "smithy.api#documentation": "<p>Queries a knowledge base and retrieves information from it.</p>",
        "smithy.api#http": {
          "code": 200,
          "method": "POST",
          "uri": "/knowledgebases/{knowledgeBaseId}/retrieve"
        },
        "smithy.api#readonly": {}
      }
    },
    "com.amazonaws.bedrockagentruntime#RetrieveRequest": {
      "type": "structure",
      "members": {
        "knowledgeBaseId": {
          "target": "smithy.api#String",
          "traits": {
            "smithy.api#documentation": "<p>The unique identifier of the knowledge base to query.</p>",
            "smithy.api#httpLabel": {},
            "smithy.api#required": {}
          }
        },
        "retrievalQuery": {
          "target": "com.amazonaws.bedrockagentruntime#KnowledgeBaseQuery",
          "traits": {
            "smithy.api#documentation": "<p>Contains the query to send the knowledge base.</p>",
            "smithy.api#required": {}
          }
        }
      },
      "traits": {
        "smithy.api#input": {}
      }
    },
    "com.amazonaws.bedrockagentruntime#KnowledgeBaseQuery": {
      "type": "structure",
      "members": {
        "text": {
          "target": "smithy.api#String",
          "traits": {
            "smithy.api#documentation": "<p>The text of the query made to the knowledge base.</p>",
            "smithy.api#required": {}
          }
        }
      }
    },
    "com.amazonaws.bedrockagentruntime#RetrieveResponse": {
      "type": "structure",
      "members": {
        "retrievalResults": {
          "target": "com.amazonaws.bedrockagentruntime#KnowledgeBaseRetrievalResults",
          "traits": {
            "smithy.api#documentation": "<p>A list of results from querying the knowledge base.</p>",
            "smithy.api#required": {}
          }
        }
      },
      "traits": {
        "smithy.api#output": {}
      }
    },
    "com.amazonaws.bedrockagentruntime#KnowledgeBaseRetrievalResults": {
      "type": "list",
      "member": {
        "target": "com.amazonaws.bedrockagentruntime#KnowledgeBaseRetrievalResult"
      }
    },
    "com.amazonaws.bedrockagentruntime#KnowledgeBaseRetrievalResult": {
      "type": "structure",
      "members": {
        "content": {
          "target": "com.amazonaws.bedrockagentruntime#RetrievalResultContent",
          "traits": {
            "smithy.api#documentation": "<p>Contains information about the content of the chunk.</p>",
            "smithy.api#required": {}
          }
        },
        "score": {
          "target": "smithy.api#Double",
          "traits": {
            "smithy.api#documentation": "<p>The level of relevance of the result to the query.</p>"
          }
        }
      }
    },
    "com.amazonaws.bedrockagentruntime#RetrievalResultContent": {
      "type": "structure",
      "members": {
        "text": {
          "target": "smithy.api#String",
          "traits": {
            "smithy.api#documentation": "<p>The cited text from the data source.</p>"
          }
        }
      }
    }
  }
}

試してないですが、複数サービスにまたがることも可能なようなので、必要なAPIに制限したMCPサーバーが構築できそうですね！

--

ついでにCDK版作っておきました。よかったらどうぞ