Objectifs du modèle Smithy
Smithy est un langage permettant de définir des services et des kits de développement logiciel (SDK). Les modèles Smithy fournissent une approche plus structurée pour définir les API par rapport à OpenAPI, et sont particulièrement utiles pour la connexion AWS à des services tels que AgentCore Gateway.
Les cibles du modèle Smithy connectent votre AgentCore passerelle à des services définis à l'aide des modèles d'API Smithy. Lorsque vous invoquez une cible de passerelle du modèle Smithy, la passerelle traduit les demandes MCP entrantes en appels d'API envoyés à ces services. La passerelle gère également le formatage des réponses.
Passez en revue les principales considérations et limites, y compris la prise en charge des fonctionnalités, pour vous aider à déterminer si un objectif Smithy est applicable à votre cas d'utilisation. Si tel est le cas, vous pouvez créer un schéma conforme aux spécifications, puis configurer les autorisations permettant à la passerelle d'accéder à la cible. Choisissez une rubrique pour en savoir plus :
Principales considérations et limites
Lorsque vous utilisez des modèles Smithy avec AgentCore Gateway, tenez compte des limites suivantes :
-
Taille maximale du modèle : 10 Mo
-
Seules les liaisons de protocole JSON sont entièrement prises en charge
-
Seul le RestJson protocole est pris en charge
Si vous envisagez d'utiliser des modèles Smithy avec AgentCore Gateway, consultez le tableau de prise en charge des fonctionnalités ci-dessous.
Bonnes pratiques de sécurité pour la configuration des terminaux
Avertissement
Lorsque vous définissez des règles de point de terminaison et des URL de serveur dans vos modèles Smithy, évitez d'utiliser des modèles de paramètres d'URL trop permissifs qui pourraient exposer votre passerelle à des risques de sécurité.
Les modèles Smithy prennent en charge la configuration dynamique des terminaux via des règles de point de terminaison et des paramètres d'URL. Toutefois, certains modèles peuvent introduire des failles de sécurité s'ils ne sont pas correctement limités. En particulier, évitez d'utiliser des modèles entièrement dynamiques tels que :
-
Paramètres d'hôte ou de domaine illimités dans les URL des points de terminaison : ou
https://{host}/api/v1https://{domain}.example.com -
Plusieurs espaces réservés non contraints dans les URL des serveurs :
https://{subdomain}.{env}.{domain}.com -
Règles de point de terminaison qui autorisent la construction d'URL arbitraires sans validation
Ces modèles peuvent potentiellement être exploités pour :
-
Rediriger les demandes vers des points de terminaison involontaires ou malveillants
-
Accès aux ressources du réseau interne ou aux services de métadonnées d'instance (Server-Side Request Forgery)
-
Exfiltrer les informations d'identification IAM ou les données sensibles
Pratiques recommandées :
-
Utilisez des URL de point de terminaison statiques et entièrement qualifiées dans la mesure du possible
-
Pour les AWS services, utilisez une résolution de point de terminaison standard avec des paramètres régionaux validés. Gateway applique la validation des AWS régions pour les services AWS
-
Si des règles de point de terminaison personnalisées sont requises, limitez les paramètres à des valeurs spécifiques et validées
-
Évitez d'exposer les paramètres bruts de l'hôte ou du domaine dans la configuration du point de terminaison de votre modèle Smithy
Pour les intégrations de AWS services, AgentCore Gateway valide automatiquement les paramètres régionaux et bloque les demandes adressées à des plages d'adresses IP privées.
Support des fonctionnalités Smithy pour Gateway AgentCore
Le tableau suivant décrit les fonctionnalités de Smithy prises en charge et non prises en charge par Gateway :
| Fonctionnalités prises en charge | Fonctions non prises en charge |
|---|---|
|
Définitions de service Définitions de structure de service basées sur les spécifications de Smithy Définitions d'opérations avec input/output formes Définitions de ressources Formes de traits RestJson Protocole Protocole de support Protocoles request/response Modèles HTTP standard Types de données Types primitifs (chaîne, entier, booléen, flottant, double) Types complexes (structures, listes, cartes) Gestion des horodatages Types de données Blob Liaisons de méthodes HTTP de base Liaisons de paramètres de chemin simples Liaisons de paramètres de requête Liaisons d'en-têtes pour les cas simples Règles de point de terminaison Les règles de point de terminaison définissent la détermination du point de terminaison d'exécution |
Support de protocole RestXml Protocole Protocole JsonRpc AwsQuery Protocole Ec2Query Protocoles personnalisés Authentification Plusieurs types d'authentification de sortie pour des API spécifiques Schémas d'authentification complexes nécessitant des décisions d'exécution Opérations Opérations de streaming Opérations nécessitant des implémentations de protocoles personnalisés |
Spécification du modèle Smithy
AgentCore Gateway fournit des modèles Smithy intégrés pour les AWS services courants. Pour voir les modèles Smithy pour les AWS services, consultez le référentiel de modèles AWS d'API
Note
AgentCore Gateway ne prend pas en charge les modèles Smithy personnalisés pour les AWS non-services.
Après avoir défini votre modèle Smithy, vous pouvez effectuer l'une des opérations suivantes :
-
Téléchargez-le dans un compartiment Amazon S3 et faites référence à l'emplacement S3 lorsque vous ajoutez la cible à votre passerelle.
-
Collez la définition en ligne lorsque vous ajoutez la cible à votre passerelle.
Développez une section pour voir des exemples de spécifications des modèles Smithy pris en charge et non pris en charge :
L'exemple suivant montre une spécification de modèle Smithy valide pour un service météo :
{ "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" } } } } } }
L'exemple suivant montre une configuration de règles de point de terminaison non valide à l'aide de 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"} } ] })
