View a markdown version of this page

Target model pandai besi - Batuan Dasar Amazon AgentCore
Pertimbangan dan keterbatasan utamaSpesifikasi model pandai besi

Target model pandai besi

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

Target model Smithy menghubungkan AgentCore gateway Anda ke layanan yang ditentukan menggunakan model Smithy API. Saat Anda memanggil target gateway model Smithy, gateway menerjemahkan permintaan MCP yang 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 keterbatasan utama

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

  • Ukuran model maksimal: 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 endpoint dan URL server dalam model Smithy Anda, hindari penggunaan pola parameter URL yang terlalu permisif yang dapat mengekspos gateway Anda ke risiko keamanan.

Model Smithy mendukung konfigurasi endpoint dinamis melalui aturan endpoint 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: atau https://{host}/api/v1 https://{domain}.example.com

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

  • Aturan titik akhir yang memungkinkan konstruksi URL arbitrer tanpa validasi

Pola-pola ini berpotensi dieksploitasi untuk:

  • Mengalihkan permintaan ke titik akhir yang tidak diinginkan atau berbahaya

  • Akses sumber daya jaringan internal atau layanan metadata instans (Server-Side Permintaan Pemalsuan)

  • Eksfiltrasi kredensyal IAM atau data sensitif

Praktik yang direkomendasikan:

  • Gunakan URL titik akhir yang 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 RestJson Protokol Dukungan protokol request/response Pola HTTP standar Jenis data Jenis data Jenis primitif (string, integer, boolean, float, ganda) Tipe kompleks (struktur, daftar, peta) Penanganan stempel waktu Tipe data gumpalan Pengikatan HTTP Pengikatan metode HTTP dasar Pengikatan parameter jalur sederhana Pengikatan parameter kueri Pengikatan header untuk kasus sederhana Aturan Endpoint Aturan Endpoint menetapkan penentuan titik akhir Runtime berdasarkan kondisi

Protokol Dukungan RestXml Protokol protokol JsonRpc protokol AwsQuery Protokol Ec2Query Protokol kustom Otentikasi Beberapa jenis otentikasi jalan keluar untuk API tertentu Skema otentikasi kompleks yang memerlukan keputusan runtime Operasi Operasi Streaming Operasi Operasi yang memerlukan implementasi protokol khusus

Spesifikasi model pandai besi

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

catatan

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

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

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

  • Tempel 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 endpoint 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"}
    }
  ]
})