View a markdown version of this page

Target model Smithy - Batu Dasar Amazon AgentCore
Pertimbangan dan batasan utamaSpesifikasi model Smithy

Terjemahan disediakan oleh mesin penerjemah. Jika konten terjemahan yang diberikan bertentangan dengan versi bahasa Inggris aslinya, utamakan versi bahasa Inggris.

Target model Smithy

Smithy adalah bahasa untuk mendefinisikan layanan dan perangkat pengembangan perangkat lunak (SDK). Model Smithy menyediakan pendekatan yang lebih terstruktur untuk mendefinisikan API dibandingkan dengan OpenAPI, dan sangat berguna untuk menghubungkan ke AWS layanan, seperti AgentCore Gateway.

Target model Smithy menghubungkan AgentCore gateway Anda ke layanan yang ditentukan menggunakan model API Smithy. Saat Anda memanggil target gateway model Smithy, gateway menerjemahkan permintaan MCP masuk ke dalam panggilan API yang dikirim ke layanan ini. Gateway juga menangani pemformatan respons.

Tinjau pertimbangan dan batasan utama, termasuk dukungan fitur, untuk membantu Anda memutuskan apakah target Smithy berlaku untuk kasus penggunaan Anda. Jika ya, Anda dapat membuat skema yang mengikuti spesifikasi dan kemudian mengatur izin untuk gateway untuk dapat mengakses target. Pilih topik untuk mempelajari lebih lanjut:

Pertimbangan dan batasan utama

Saat menggunakan model Smithy dengan AgentCore Gateway, perhatikan batasan berikut:

  • Ukuran model maksimum: 10MB

  • Hanya binding protokol JSON yang didukung penuh

  • Hanya RestJson protokol yang didukung

Dalam mempertimbangkan menggunakan model Smithy dengan AgentCore Gateway, tinjau tabel dukungan fitur berikut.

Praktik terbaik keamanan untuk konfigurasi titik akhir

Awas

Saat menentukan aturan titik akhir dan URL server dalam model Smithy Anda, hindari menggunakan pola parameter URL yang terlalu permisif yang dapat mengekspos gateway Anda terhadap risiko keamanan.

Model Smithy mendukung konfigurasi titik akhir dinamis melalui aturan titik akhir dan parameter URL. Namun, pola tertentu dapat menimbulkan kerentanan keamanan jika tidak dibatasi dengan benar. Secara khusus, hindari menggunakan pola yang sepenuhnya dinamis seperti:

  • Parameter host atau domain tidak terbatas di URL titik akhir: https://{host}/api/v1 atau https://{domain}.example.com

  • Beberapa placeholder tidak dibatasi di URL server: https://{subdomain}.{env}.{domain}.com

  • Aturan titik akhir yang memungkinkan konstruksi URL sewenang-wenang tanpa validasi

Pola-pola ini berpotensi dieksploitasi untuk:

  • Mengalihkan permintaan ke titik akhir yang tidak diinginkan atau berbahaya

  • Mengakses sumber daya jaringan internal atau layanan metadata instance (Re Server-Side quest Forgery)

  • Eksfiltrasi kredentif IAM atau data sensitif

Praktik yang direkomendasikan:

  • Gunakan URL titik akhir statis dan memenuhi syarat bila memungkinkan

  • Untuk AWS layanan, andalkan resolusi titik akhir standar dengan parameter wilayah yang divalidasi. Gateway memberlakukan validasi AWS wilayah untuk layanan AWS

  • Jika aturan titik akhir khusus diperlukan, batasi parameter ke nilai tertentu yang divalidasi

  • Hindari mengekspos parameter host atau domain mentah dalam konfigurasi titik akhir model Smithy Anda

Untuk integrasi AWS layanan, AgentCore Gateway secara otomatis memvalidasi parameter wilayah dan memblokir permintaan ke rentang IP pribadi.

Dukungan fitur Smithy untuk Gateway AgentCore

Tabel berikut menguraikan fitur Smithy yang didukung dan tidak didukung oleh Gateway:

Fitur yang Didukung Fitur-Fitur yang Tidak Didukung

Definisi Layanan Definisi struktur layanan berdasarkan spesifikasi Smithy Definisi operasi dengan input/output bentuk Definisi sumber daya Bentuk sifat Protokol Protokol dukungan RestJson P request/response ola HTTP standar Jenis data Jenis primitif (string, integer, boolean, float, ganda) Jenis kompleks (struktur, daftar, peta) Penanganan stempel waktu Jenis data Blob Pengikatan HTTP Pengikatan metode HTTP dasar Pengikatan parameter jalur sederhana Pengikatan parameter kueri Header binding untuk kasus sederhana Aturan titik akhir Aturan titik akhir menetapkan penentuan titik akhir Runtime berdasarkan kondisi

Protokol Mendukung RestXml protokol JsonRpc protokol AwsQuery protokol Ec2Query Protokol khusus Otentikasi Beberapa jenis otentikasi keluar untuk API tertentu Skema otentikasi kompleks yang memerlukan keputusan runtime Operasi Operasi streaming Operasi yang memerlukan implementasi protokol khusus

Spesifikasi model Smithy

AgentCore Gateway menyediakan model Smithy bawaan untuk AWS layanan umum. Untuk melihat model Smithy untuk AWS layanan, lihat repositori AWS Model API.

catatan

AgentCore Gateway tidak mendukung model Smithy khusus untuk non-AWS layanan.

Setelah Anda menentukan model Smithy Anda, Anda dapat melakukan salah satu hal berikut:

  • Unggah ke bucket Amazon S3 dan rujuk ke lokasi S3 saat Anda menambahkan target ke gateway Anda.

  • Tempelkan definisi sebaris saat Anda menambahkan target ke gateway Anda.

Perluas bagian untuk melihat contoh spesifikasi model Smithy yang didukung dan tidak didukung:

Contoh berikut menunjukkan spesifikasi model Smithy yang valid untuk layanan cuaca:

{
  "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"
          }
        }
      }
    }
  }
}

Contoh berikut menunjukkan konfigurasi aturan titik akhir yang tidak valid menggunakan 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"}
    }
  ]
})