View a markdown version of this page

Smithy モデルターゲット - Amazon Bedrock AgentCore
主な考慮事項と制限事項Smithy モデル仕様

Smithy モデルターゲット

Smithy は、 サービスおよびソフトウェア開発キット (SDKs。Smithy モデルは、OpenAPI と比較して APIs を定義するためのより構造化されたアプローチを提供し、特に AgentCore Gateway などの AWS サービスへの接続に役立ちます。

Smithy モデルターゲットは、AgentCore ゲートウェイを Smithy API モデルを使用して定義されたサービスに接続します。Smithy モデルゲートウェイターゲットを呼び出すと、ゲートウェイは受信 MCP リクエストをこれらのサービスに送信される API コールに変換します。ゲートウェイはレスポンスのフォーマットも処理します。

Smithy ターゲットがユースケースに適しているかどうかを判断するために、機能サポートを含む重要な考慮事項と制限事項を確認してください。その場合は、仕様に従ったスキーマを作成し、ゲートウェイがターゲットにアクセスできるようにアクセス許可を設定できます。詳細情報については、トピックを選択してください。

主な考慮事項と制限事項

AgentCore Gateway で Smithy モデルを使用する場合は、次の制限に注意してください。

  • 最大モデルサイズ: 10MB

  • JSON プロトコルバインディングのみが完全にサポートされています

  • RestJson プロトコルのみがサポートされています

AgentCore Gateway で Smithy モデルを使用することを検討する際は、次の機能サポート表を確認してください。

エンドポイント設定のセキュリティのベストプラクティス

警告

Smithy モデルでエンドポイントルールとサーバー URLs を定義するときは、ゲートウェイをセキュリティリスクにさらす可能性のある過度に寛容な URL パラメータパターンを使用しないでください。

Smithy モデルは、エンドポイントルールと URL パラメータを通じて動的エンドポイント設定をサポートします。ただし、特定のパターンでは、適切に制約されていない場合、セキュリティの脆弱性が発生する可能性があります。具体的には、次のような完全に動的なパターンを使用しないでください。

  • エンドポイント URLs: https://{host}/api/v1または https://{domain}.example.com

  • サーバー URLs の複数の制約のないプレースホルダー: https://{subdomain}.{env}.{domain}.com

  • 検証なしで任意の URL 構築を許可するエンドポイントルール

これらのパターンは、次の目的で悪用される可能性があります。

  • 意図しないエンドポイントまたは悪意のあるエンドポイントにリクエストをリダイレクトする

  • 内部ネットワークリソースまたはインスタンスメタデータサービスへのアクセス (サーバー側のリクエスト偽造)

  • IAM 認証情報または機密データを抽出する

推奨されるプラクティス:

  • 可能な限り静的で完全修飾エンドポイント URLs

  • AWS サービスの場合は、検証済みのリージョンパラメータで標準のエンドポイント解決に依存します。ゲートウェイが AWS サービスの AWS リージョン検証を強制する

  • カスタムエンドポイントルールが必要な場合は、パラメータを特定の検証済み値に制限します。

  • Smithy モデルのエンドポイント設定で raw ホストまたはドメインパラメータを公開しない

AWS サービス統合の場合、AgentCore Gateway はリージョンパラメータを自動的に検証し、プライベート IP 範囲へのリクエストをブロックします。

AgentCore Gateway の Smithy 機能のサポート

次の表は、Gateway でサポートおよびサポートされていない Smithy 機能の概要を示しています。

サポートされている機能 サポートされていない機能

サービス定義 Smithy 仕様に基づくサービス構造定義 入力/出力形状を持つオペレーション定義 リソース定義 特性形状 プロトコルサポート RestJson プロトコル 標準 HTTP リクエスト/レスポンスパターン データ型 プリミティブ型 (文字列、整数、ブール値、浮動小数点数、二重値) 複雑な型 (構造、リスト、マップ) タイムスタンプ処理 Blob データ型 HTTP バインディング 基本的な HTTP メソッドバインディング シンプルパスパラメータバインディング クエリパラメータバインディング シンプルケースのヘッダーバインディング エンドポイントルールセット 条件に基づくランタイムエンドポイント判定

プロトコルサポート RestXml プロトコル JsonRpc プロトコル AwsQuery プロトコル Ec2Query プロトコル カスタムプロトコル 認証 特定の APIs に複数の Egress 認証タイプ ランタイム決定を必要とする複雑な認証スキーム オペレーション ストリーミングオペレーション オペレーション カスタムプロトコル実装を必要とするオペレーション

Smithy モデル仕様

AgentCore Gateway は、一般的な AWS サービス用の組み込み Smithy モデルを提供します。 AWS サービスの Smithy モデルを確認するには、 AWS API Models リポジトリを参照してください。

注記

AgentCore Gateway は、AWS サービス以外のカスタム Smithy モデルをサポートしていません。

Smithy モデルを定義したら、次のいずれかを実行できます。

  • Amazon S3 バケットにアップロードし、ゲートウェイにターゲットを追加するときに S3 の場所を参照します。

  • ゲートウェイにターゲットを追加するときに、定義をインラインで貼り付けます。

セクションを展開すると、サポートされている Smithy モデル仕様とサポートされていない Smithy モデル仕様の例が表示されます。

次の例は、気象サービスの有効な Smithy モデル仕様を示しています。

{
  "smithy": "2.0",
  "metadata": {
    "suppressions": []
  },
  "shapes": {
    "example.weather#WeatherService": {
      "type": "service",
      "version": "1.0.0",
      "operations": [
        {
          "target": "example.weather#GetCurrentWeather"
        }
      ],
      "traits": {
        "aws.protocols#restJson1": {},
        "smithy.api#documentation": "Weather service for retrieving weather information"
      }
    },
    "example.weather#GetCurrentWeather": {
      "type": "operation",
      "input": {
        "target": "example.weather#GetCurrentWeatherInput"
      },
      "output": {
        "target": "example.weather#GetCurrentWeatherOutput"
      },
      "errors": [
        {
          "target": "smithy.framework#ValidationException"
        }
      ],
      "traits": {
        "smithy.api#http": {
          "method": "GET",
          "uri": "/weather"
        },
        "smithy.api#documentation": "Get current weather for a location"
      }
    },
    "example.weather#GetCurrentWeatherInput": {
      "type": "structure",
      "members": {
        "location": {
          "target": "smithy.api#String",
          "traits": {
            "smithy.api#required": {},
            "smithy.api#httpQuery": "location",
            "smithy.api#documentation": "City name or coordinates"
          }
        },
        "units": {
          "target": "example.weather#Units",
          "traits": {
            "smithy.api#httpQuery": "units",
            "smithy.api#default": "metric",
            "smithy.api#documentation": "Units of measurement (metric or imperial)"
          }
        }
      }
    },
    "example.weather#GetCurrentWeatherOutput": {
      "type": "structure",
      "members": {
        "location": {
          "target": "smithy.api#String",
          "traits": {
            "smithy.api#documentation": "Location name"
          }
        },
        "temperature": {
          "target": "smithy.api#Float",
          "traits": {
            "smithy.api#documentation": "Current temperature"
          }
        },
        "conditions": {
          "target": "smithy.api#String",
          "traits": {
            "smithy.api#documentation": "Weather conditions description"
          }
        },
        "humidity": {
          "target": "smithy.api#Float",
          "traits": {
            "smithy.api#documentation": "Humidity percentage"
          }
        }
      }
    },
    "example.weather#Units": {
      "type": "enum",
      "members": {
        "metric": {
          "target": "smithy.api#Unit",
          "traits": {
            "smithy.api#enumValue": "metric"
          }
        },
        "imperial": {
          "target": "smithy.api#Unit",
          "traits": {
            "smithy.api#enumValue": "imperial"
          }
        }
      }
    }
  }
}

次の例は、Smithy を使用した無効なエンドポイントルール設定を示しています。

@endpointRuleSet({
  "rules": [
    {
      "conditions": [{"fn": "booleanEquals", "argv": [{"ref": "UseFIPS"}, true]}],
      "endpoint": {"url": "https://weather-fips.{Region}.example.com"}
    },
    {
      "endpoint": {"url": "https://weather.{Region}.example.com"}
    }
  ]
})