Les traductions sont fournies par des outils de traduction automatique. En cas de conflit entre le contenu d'une traduction et celui de la version originale en anglais, la version anglaise prévaudra.
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 proposent une approche plus structurée de la définition des 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 requêtes 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écider si une cible Smithy est applicable à votre cas d'utilisation. Si c'est le cas, vous pouvez créer un schéma conforme aux spécifications, puis configurer des autorisations pour que la passerelle puisse 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 les modèles Smithy avec AgentCore Gateway, consultez le tableau de prise en charge des fonctionnalités suivant.
Meilleures 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. Cependant, 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 :
https://{host}/api/v1ouhttps://{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 permettent la construction arbitraire d'URL sans validation
Ces modèles peuvent potentiellement être exploités pour :
-
Rediriger les demandes vers des terminaux non intentionnels ou malveillants
-
Accédez à des ressources réseau internes ou à des services de métadonnées d'instance (Server-Side Request Forgery)
-
Exfiltrez les informations d'identification IAM ou les données sensibles
Pratiques recommandées :
-
Utilisez des URL de point de terminaison statiques et complètes dans la mesure du possible
-
Pour les AWS services, utilisez une résolution de point de terminaison standard avec des paramètres de région validés. Gateway applique AWS la validation des 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 des terminaux de votre modèle Smithy
Pour les intégrations de AWS services, AgentCore Gateway valide automatiquement les paramètres de région et bloque les demandes vers des plages d'adresses IP privées.
Support des fonctionnalités de Smithy pour Gateway AgentCore
Le tableau suivant décrit les fonctionnalités de Smithy qui sont prises en charge et non prises en charge par Gateway :
| Fonctionnalités prises en charge | Fonctions non prises en charge |
|---|---|
|
Définitions des services Définitions des structures de service basées sur les spécifications de Smithy Définitions des opérations avec input/output formes Définitions des ressources Formes des 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 de l'horodatage 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 En-tête liaisons pour les cas simples Règles de point de terminaison ensembles de règles de point de terminaison Détermination du point de terminaison d'exécution en fonction des conditions |
Protocole Support RestXml protocolaire 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
Note
AgentCore Gateway ne prend pas en charge les modèles Smithy personnalisés pour les applications autres que les AWS 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 de 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éorologique :
{ "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"} } ] })
